diff --git a/content/blog/extend-existing-systems-with-ai.de.mdx b/content/blog/extend-existing-systems-with-ai.de.mdx index a2e5c10..650e745 100644 --- a/content/blog/extend-existing-systems-with-ai.de.mdx +++ b/content/blog/extend-existing-systems-with-ai.de.mdx @@ -1,6 +1,6 @@ --- title: "Mach dein bestehendes Geschäftssystem KI-nativ — ohne Migration" -description: "Verbinde ObjectOS mit der Datenbank, die du bereits betreibst, modelliere die Tabellen als Objekte und lass KI echte Daten abfragen und bearbeiten — unter deinen Berechtigungen, auf deinen Servern." +description: "Verbinde ObjectOS mit der Datenbank, die du bereits betreibst, lass einen Coding-Agenten die Tabellen als Objekte modellieren und setze KI auf echte Daten — unter deinen Berechtigungen, auf deinen Servern, ohne das Ursprungssystem anzufassen." author: ObjectStack Team date: 2026-05-30 tags: @@ -9,116 +9,246 @@ tags: - Architecture --- -Die meisten „Bring KI in dein Geschäft"-Versprechen setzen stillschweigend -einen Neuaufbau voraus: die Daten in eine neue Plattform heben, die -Workflows neu implementieren, das Team neu schulen. Genau das will niemand. -Das System of Record — das CRM, das ERP, das Ticketing-Tool, das -selbstgebaute Back Office — funktioniert bereits, und genau dort liegen die -Daten schon. +Die meisten „Bring KI in dein Business"-Pitches setzen heimlich einen +Neuaufbau voraus: Daten auf eine neue Plattform heben, Workflows neu +implementieren, das Team umschulen und beten, dass die Migration gelingt. +Genau das will niemand. Das System of Record — das CRM, das ERP, das +Ticketing-Tool, das selbstgebaute Backoffice — funktioniert bereits, und +die Daten liegen längst dort. -ObjectOS vertritt die gegenteilige Haltung. **Du migrierst nicht. Du verbindest.** +ObjectOS nimmt die Gegenposition ein. **Du migrierst nicht. Du verbindest.** ## Die Idee in einem Satz -Richte ObjectOS auf deine bestehende Datenbank, beschreibe die Tabellen, die -dich interessieren, als Objekte, und jeder KI-Agent, jeder Flow und jedes -Dashboard arbeitet sofort mit diesen Daten — automatisch an das richtige -System geroutet, geregelt durch dieselben Berechtigungen, die deine Nutzer -bereits haben. +Richte ObjectOS auf deine bestehende Datenbank, beschreibe die Tabellen, +die dich interessieren, als Objekte — und jeder KI-Agent, jeder Flow, jede +API und jedes Dashboard arbeitet sofort auf diesen Daten, automatisch an +das richtige System geroutet und durch dieselben Berechtigungen geregelt, +die deine Nutzer bereits haben. -Die ursprüngliche Anwendung ändert sich nicht. Die Zeilen wandern nicht. -ObjectOS wird zur KI-nativen, berechtigungsbewussten Oberfläche über dem, -was du bereits betreibst. +Die ursprüngliche Anwendung ändert sich nicht. Die Zeilen bewegen sich +nicht. ObjectOS wird zur KI-nativen, berechtigungsbewussten Oberfläche auf +dem, was du ohnehin betreibst. + +## Ein konkretes Bild + +Angenommen, dein Vertriebsteam läuft auf einem Postgres-CRM mit 40 +Tabellen. Accounts, Kontakte, Opportunities, Positionen, Aktivitäten — +jahrelange echte Daten, eine Produktivanwendung, die deine Reps täglich +nutzen. Die Führung will zwei Dinge: Leute sollen diese Daten *in +natürlicher Sprache befragen* können („Welche Enterprise-Deals sind aus Q2 +gerutscht, und wer verantwortet sie?"), und Automatisierungen sollen +sicher darauf agieren. + +Die Neuaufbau-Antwort ist ein Sechs-Monats-Projekt. Die ObjectOS-Antwort +ist ein Nachmittag: + +1. Die CRM-Datenbank als **schreibgeschützte** Datenquelle verbinden. +2. Einen Coding-Agenten das Dutzend Tabellen, die dich wirklich + interessieren, als Objekte modellieren lassen. +3. Deine Daten befragen und die erste Automatisierung verdrahten. + +Niemand fasst das CRM an. Die Reps merken nichts. Du bekommst eine +KI-native Schicht auf exakt denselben Zeilen. ## Wie es heute funktioniert -Es gibt vier Schritte, und keiner davon lautet „bau deine App neu": - -1. **Verbinde die Datenbank als Datasource.** Eine Datasource ist eine - benannte Verbindung — Postgres, MySQL, MongoDB, SQLite. Die - Zugangsdaten stammen aus der Umgebung, und die Verbindung kann - schreibgeschützt sein, wenn du zunächst nur analysieren möchtest. - - ```ts - import type { Datasource } from '@objectstack/spec'; - - export const BusinessDb: Datasource = { - name: 'business_primary', - label: 'Business System (Postgres)', - driver: 'postgres', - config: { - connection: { - host: process.env.BIZ_DB_HOST, - user: process.env.BIZ_DB_USER, - password: process.env.BIZ_DB_PASSWORD, - database: process.env.BIZ_DB_NAME, - }, - }, - active: true, - }; - ``` - -2. **Modelliere die Tabellen als Objekte** — und du musst sie nicht von - Hand eintippen. Richte einen Coding-Agenten wie Claude Code auf das - verbundene Schema und bitte ihn, pro Tabelle eine Objektdatei auf - Quellebene zu generieren. Unsere - [`hotcrm`](https://github.com/objectstack-ai/hotcrm)-Referenz-App - zeigt die genaue Form dieser Ausgabe: ein `ObjectSchema.create({ … })` - mit typisierten `Field.*`-Definitionen und `Field.lookup(...)` für - Fremdschlüssel. Du prüfst und verfeinerst; das Ergebnis gehört dir. - -3. **Binde Objekte an die Datasource** — pro Objekt oder mit einer - Routing-Regel für einen ganzen Namespace: - - ```ts - datasourceMapping: [ - { namespace: 'biz', datasource: 'business_primary' }, - { default: true, datasource: 'default' }, - ] - ``` - -4. **Lass die KI arbeiten.** Sobald eine Tabelle ein Objekt ist, arbeitet - die KI-Schicht kostenlos damit. Agenten fragen über ObjectQL ab, das - jedes Objekt zu seiner Datenbank routet — und jede Abfrage läuft als der - **angemeldete Nutzer** und befolgt Berechtigungen auf Objekt-, Datensatz- - und Feldebene. +Vier Schritte, und keiner davon heißt „bau deine App neu". + +### 1. Die Datenbank als Datenquelle verbinden + +Eine Datenquelle ist eine benannte Verbindung — Postgres, MySQL, MongoDB, +SQLite. Zugangsdaten kommen aus der Umgebung, niemals inline im Code. Wenn +du zuerst nur analysieren willst, richte sie auf eine Read-Replica oder +einen schreibgeschützten DB-Nutzer — Schreibzugriffe sind dann schlicht +unmöglich. + +```ts +import type { Datasource } from '@objectstack/spec'; + +export const BusinessDb: Datasource = { + name: 'business_primary', + label: 'Business System (Postgres)', + driver: 'postgres', + config: { + connection: { + host: process.env.BIZ_DB_HOST, + user: process.env.BIZ_DB_USER, + password: process.env.BIZ_DB_PASSWORD, + database: process.env.BIZ_DB_NAME, + }, + }, + pool: { min: 1, max: 10 }, + active: true, +}; +``` + +### 2. Die Tabellen als Objekte modellieren — mit einem Coding-Agenten + +Diesen Schritt erwarten alle als langsam, und das ist er nicht. Du tippst +kein Objekt pro Tabelle von Hand. Du richtest einen Coding-Agenten wie +**Claude Code** auf das verbundene Schema und lässt ihn Introspektion und +ersten Entwurf erledigen. Ein Prompt so schlicht wie: + +> „Verbinde dich mit der Datenquelle `business_primary`. Erzeuge für jede +> dieser Tabellen — `accounts`, `contacts`, `opportunities`, `line_items` — +> eine Datei `src/objects/.object.ts` mit `ObjectSchema.create`. +> Mappe SQL-Spalten auf die passenden `Field.*`-Typen, mach aus +> Fremdschlüsseln `Field.lookup(...)` und setze auf jedem Objekt +> `datasource: 'business_primary'`." + +Der Agent liest die echten Spalten, Typen und Fremdschlüssel und schreibt +Objektdateien auf Quellcode-Ebene. Unsere +[`hotcrm`](https://github.com/objectstack-ai/hotcrm)-Referenz-App zeigt die +exakte Form dieser Ausgabe: + +```ts +import { ObjectSchema, Field } from '@objectstack/spec/data'; + +export const Opportunity = ObjectSchema.create({ + name: 'biz_opportunity', + label: 'Opportunity', + datasource: 'business_primary', + fields: { + name: Field.text({ label: 'Name', required: true }), + account: Field.lookup({ label: 'Account', reference_to: 'biz_account' }), + amount: Field.currency({ label: 'Amount' }), + stage: Field.select({ label: 'Stage', options: [/* … */] }), + close_date: Field.date({ label: 'Close Date' }), + }, +}); +``` + +Weil die Ausgabe **gewöhnlicher Quellcode ist, den du besitzt und +commitest**, behältst du die Kontrolle: Spalten, die zählen, behalten; +solche, die du nicht offenlegen willst, weglassen; Labels, Validierungen +und Berechtigungen darüberlegen. Der Agent bringt dich in Minuten zu einem +prüfbaren Entwurf; du machst ihn produktionsreif. + +### 3. Objekte an die Datenquelle binden + +Jedes Objekt trägt ein `datasource`. Setze es pro Objekt oder deklariere +einmal eine Routing-Regel für einen ganzen Namensraum und lass jedes Objekt +darunter erben: + +```ts +datasourceMapping: [ + { namespace: 'biz', datasource: 'business_primary' }, + { default: true, datasource: 'default' }, +] +``` + +Regeln matchen nach Namensraum, Paket oder Objektnamen-Glob; der erste +Treffer gewinnt. Entscheidungen zur Datenresidenz liegen an einer Stelle +statt über Dateien verstreut. + +### 4. Die KI arbeiten lassen + +Sobald eine Tabelle ein Objekt ist, arbeitet die KI-Schicht gratis darauf. +Die Agenten und Tools von ObjectOS — `list_objects`, `describe_object`, +`query_records`, `aggregate_data` und der Data-Chat-Agent — laufen alle +durch **ObjectQL**, das jedes Objekt an seine gebundene Datenquelle routet +und Filter, Sortierung und Aggregationen *in die Datenbank pushed*, wenn +der Treiber das unterstützt. + +Wenn ein Nutzer also fragt: + +> „Welche Enterprise-Opportunities sind aus Q2 gerutscht, und wer +> verantwortet sie?" + +schaufelt der Agent nicht die ganze Tabelle in den Prompt. Er kompiliert +das zu einer ObjectQL-Abfrage gegen `biz_opportunity` — ein `WHERE` auf +Stage und Abschlussdatum, ein Join auf den Owner — führt es als +`SELECT … WHERE …` auf deinem Postgres aus und antwortet aus den echten, +aktuellen Zeilen. Und entscheidend: Es führt diese Abfrage **als der +angemeldete Nutzer** aus — wenn ein Rep im CRM die Deals einer anderen +Region nicht sehen darf, kann es der Agent auch nicht. ## Warum das sicher ist Der Einwand gegen „KI auf unseren Geschäftsdaten" lautet immer Governance, und genau dort leistet die Runtime die Arbeit: -- **KI handelt als der Nutzer, nie über ihm.** Ein Agent sieht genau das, - was die Person dahinter sehen darf — durchgesetzt in der Runtime, nicht - im Prompt. -- **Standardmäßig schreibgeschützt, wenn du es möchtest.** Binde Objekte an - eine schreibgeschützte Verbindung oder einen schreibgeschützten DB-Nutzer. - Analysiere die Produktion sicher; aktiviere Schreibzugriffe bewusst. -- **Alles auditiert.** Jeder Lese-, Schreib- und Eskalationsvorgang — ob - Mensch oder Agent — wird mit Wer, Was, Wann und Warum aufgezeichnet. +- **KI agiert als der Nutzer, nie über ihm.** Ein Agent sieht genau das, + was die Person dahinter sehen darf — Berechtigungen auf Objekt-, + Datensatz- und Feldebene, erzwungen in der Runtime, nicht im Prompt. +- **Standardmäßig schreibgeschützt, wenn du willst.** Binde Objekte an eine + schreibgeschützte Verbindung oder einen DB-Nutzer. Analysiere die + Produktion sicher; aktiviere Schreibzugriffe bewusst, Objekt für Objekt. +- **Alles auditiert.** Jeder Lese- und Schreibvorgang und jede Eskalation — + ob Mensch oder Agent — wird mit Wer, Was, Wann und Warum protokolliert. - **Deine Daten bleiben in deinem Netzwerk.** ObjectOS läuft in deiner - Umgebung. Geschäftsdaten und Prompts verlassen deinen Perimeter nie. + Umgebung. Geschäftsdaten und Prompts verlassen deine Grenze nie. + +## Neuaufbau vs. verbinden + +| | Neuaufbau auf neuer Plattform | Verbinden mit ObjectOS | +|---|---|---| +| **Zeit bis zum ersten Nutzen** | Monate | Ein Nachmittag | +| **Risiko für das System of Record** | Hoch — Migration, Dual-Writes, Cutover | Keins — die Quell-App bleibt unberührt | +| **Wo die Daten liegen** | Verschoben | Bleiben genau, wo sie sind | +| **Modellierungsaufwand** | Jede Entität von Hand neu bauen | Agent entwirft Objekte aus dem Live-Schema | +| **Berechtigungen** | Neu gebaut und neu auditiert | Geerbt; KI folgt demselben Modell | +| **Umkehrbarkeit** | Schwer rückgängig zu machen | Datenquelle trennen — nichts hat sich geändert | + +## Was du am ersten Tag bekommst + +Sobald eine Handvoll Tabellen modelliert und gebunden ist: + +- **Analyse in natürlicher Sprache** über Live-Datensätze, berechnet durch + ObjectQL — kein veralteter Export. +- **Gesteuerte Automatisierung.** Flows und Aktionen lesen und (wo erlaubt) + schreiben dieselben Daten, jeder Schritt auditiert. +- **Eine generierte API und Konsole.** REST/GraphQL-Endpunkte und + Admin-Screens stammen aus denselben Metadaten — keine zusätzliche + Integrationsschicht. +- **Ein Berechtigungsmodell.** Die Grenze für Menschen gilt identisch für + KI-Traffic. + +## Ausgeliefert vs. kommend + +Der obige Ablauf funktioniert **heute** mit ausgelieferten Bausteinen: +Datenquellen, Routing pro Objekt, fähigkeitsbewusstes ObjectQL-Pushdown und +die KI-Agenten-Schicht. Die Objektmodellierung erfolgt mit einem +Coding-Agenten gegen dein verbundenes Schema — genauso, wie die +`hotcrm`-Objekte verfasst wurden. + +Eine reichhaltigere, **schlüsselfertige Föderation** — Schema-Import in +einem Schritt, Bindung an extern besessene Schemas und eingebaute +Schreib-Sicherheitsgates — ist unter +[ADR-0015](https://github.com/objectstack-ai/framework/blob/main/docs/adr/0015-external-datasource-federation.md) +(Status: *Proposed*) in aktiver Ausgestaltung. Wir schreiben mehr, sobald +es landet. Bis dahin ist der dokumentierte Weg — verbinden, modellieren, +binden, abfragen — der unterstützte. -## Was ausgeliefert ist vs. was kommt +## Häufige Fragen -Der oben beschriebene Ablauf funktioniert **heute** mit ausgelieferten -Bausteinen: Datasources, Routing pro Objekt, capability-bewusster -ObjectQL-Pushdown und die KI-Agenten-Schicht. Die Objektgenerierung erfolgt -mit einem Coding-Agenten gegen dein verbundenes Schema — auf dieselbe Weise, -wie die `hotcrm`-Objekte erstellt wurden. +**Muss ich jede Tabelle modellieren?** Nein. Modelliere nur die Tabellen, +die KI und Automatisierung anfassen sollen. Der Rest der Datenbank wird +ignoriert. -Eine reichhaltigere, **schlüsselfertige Föderation** — einstufiger -Schema-Import, Bindung an extern verwaltete Schemata und eingebaute -Schreibsicherheits-Gates — befindet sich in aktiver Konzeption unter -[ADR-0015](https://github.com/objectstack-ai/framework/blob/main/docs/adr/0015-external-datasource-federation.md) -(Status: *Proposed*). Wir schreiben mehr dazu, sobald es verfügbar ist. Bis -dahin ist der dokumentierte Weg der unterstützte. +**Schreibt das in meine Produktionsdatenbank?** Nur, wenn du es zulässt. +Bind an eine schreibgeschützte Verbindung oder einen DB-Nutzer, und +Schreiben ist unmöglich; aktiviere es bewusst, pro Objekt, wenn du bereit +bist. + +**Gehen meine Daten an einen Modellanbieter?** ObjectOS läuft in deiner +Umgebung, und Abfragen laufen gegen deine Datenbank. Du steuerst, welcher +KI-Anbieter konfiguriert ist und was er sehen darf. + +**Was, wenn sich mein Schema ändert?** Lass den Coding-Agenten erneut gegen +das aktualisierte Schema laufen, um die betroffenen Objekte neu zu +generieren oder zu diffen — es sind nur Quelldateien in deinem Repo. ## Probier es aus -- [Data Sources](/docs/configure/data-sources) — der vollständige Authoring-Leitfaden -- [Bestehende Systeme erweitern](/docs/extend-existing-systems) — das Szenario, von Anfang bis Ende -- [KI-Agenten](/docs/build/agents) — deklarative Agenten über deinen Objekten +- [Datenquellen](/docs/configure/data-sources) — der vollständige + Autorenleitfaden +- [Bestehende Systeme erweitern](/docs/extend-existing-systems) — das + Szenario, von Anfang bis Ende +- [KI-Agenten](/docs/build/agents) — deklarative Agenten über deinen + Objekten -Wenn du bereits eine Geschäftsdatenbank hast, bist du fast am Ziel. Verbinde -sie, modelliere ein paar Tabellen und stell deinen Daten eine Frage. +Wenn du bereits eine Geschäftsdatenbank hast, bist du fast am Ziel. +Verbinde sie, modelliere ein paar Tabellen und stell deinen Daten eine +Frage. diff --git a/content/blog/extend-existing-systems-with-ai.es.mdx b/content/blog/extend-existing-systems-with-ai.es.mdx index a8351dc..d4a7c58 100644 --- a/content/blog/extend-existing-systems-with-ai.es.mdx +++ b/content/blog/extend-existing-systems-with-ai.es.mdx @@ -1,6 +1,6 @@ --- title: "Haz que tu sistema de negocio existente sea AI-Native — sin una migración" -description: "Conecta ObjectOS a la base de datos que ya ejecutas, modela las tablas como objetos, y deja que la IA consulte y actúe sobre datos reales — bajo tus permisos, en tus servidores." +description: "Conecta ObjectOS a la base de datos que ya ejecutas, deja que un agente de código modele las tablas como objetos y pon IA sobre datos reales — bajo tus permisos, en tus servidores, sin tocar el sistema original." author: ObjectStack Team date: 2026-05-30 tags: @@ -9,113 +9,243 @@ tags: - Architecture --- -La mayoría de las propuestas de "añade IA a tu negocio" asumen en silencio una -reconstrucción: levantar los datos a una nueva plataforma, reimplementar los -flujos de trabajo, reentrenar al equipo. Esa es la parte que nadie quiere. El -sistema de registro — el CRM, el ERP, la herramienta de tickets, el back office -hecho en casa — ya funciona, y ya es donde viven los datos. +La mayoría de los discursos de "añade IA a tu negocio" asumen en silencio +una reconstrucción: llevar los datos a una nueva plataforma, reimplementar +los flujos de trabajo, reentrenar al equipo y rezar para que la migración +salga bien. Esa es la parte que nadie quiere. El sistema de registro — el +CRM, el ERP, la herramienta de tickets, el back office hecho en casa — ya +funciona, y los datos ya están ahí. ObjectOS adopta la postura opuesta. **No migras. Conectas.** -## La idea en una sola frase +## La idea en una frase -Apunta ObjectOS a tu base de datos existente, describe las tablas que te -importan como objetos, y cada agente de IA, flujo y dashboard funciona de -inmediato sobre esos datos — enrutados automáticamente al sistema correcto, +Apunta ObjectOS a tu base de datos existente, describe como objetos las +tablas que te importan, y cada agente de IA, flujo, API y panel trabaja de +inmediato sobre esos datos — enrutados automáticamente al sistema correcto y gobernados por los mismos permisos que tus usuarios ya tienen. -La aplicación original no cambia. Las filas no se mueven. ObjectOS se convierte -en la superficie AI-native y consciente de los permisos sobre lo que ya -ejecutas. +La aplicación original no cambia. Las filas no se mueven. ObjectOS se +convierte en la superficie AI-native y consciente de permisos sobre lo que +ya ejecutas. + +## Una imagen concreta + +Supón que tu equipo de ventas funciona sobre un CRM en Postgres de 40 +tablas. Cuentas, contactos, oportunidades, líneas de pedido, actividades — +años de datos reales, una aplicación en producción que tus comerciales usan +a diario. La dirección quiere dos cosas: que la gente pueda *hacer +preguntas* a esos datos en lenguaje natural ("¿qué oportunidades enterprise +se cayeron del Q2, y quién las lleva?") y que las automatizaciones actúen +sobre ellos de forma segura. + +La respuesta de reconstrucción es un proyecto de seis meses. La respuesta de +ObjectOS es una tarde: + +1. Conecta la base de datos del CRM como una fuente de datos de **solo + lectura**. +2. Haz que un agente de código modele como objetos la docena de tablas que + de verdad te importan. +3. Hazle preguntas a tus datos y monta la primera automatización. + +Nadie toca el CRM. Los comerciales ni se enteran. Obtienes una capa +AI-native sobre exactamente las mismas filas. ## Cómo funciona hoy -Hay cuatro pasos, y ninguno de ellos es "reconstruye tu app": - -1. **Conecta la base de datos como un datasource.** Un datasource es una - conexión con nombre — Postgres, MySQL, MongoDB, SQLite. Las credenciales - provienen del entorno, y la conexión puede ser de solo lectura si solo - quieres analizar primero. - - ```ts - import type { Datasource } from '@objectstack/spec'; - - export const BusinessDb: Datasource = { - name: 'business_primary', - label: 'Business System (Postgres)', - driver: 'postgres', - config: { - connection: { - host: process.env.BIZ_DB_HOST, - user: process.env.BIZ_DB_USER, - password: process.env.BIZ_DB_PASSWORD, - database: process.env.BIZ_DB_NAME, - }, - }, - active: true, - }; - ``` - -2. **Modela las tablas como objetos** — y no tienes que escribirlas a mano. - Apunta un agente de programación como Claude Code al esquema conectado y - pídele que genere un archivo de objeto a nivel de fuente por tabla. Nuestra - app de referencia [`hotcrm`](https://github.com/objectstack-ai/hotcrm) - muestra la forma exacta que adopta esa salida: un `ObjectSchema.create({ … })` - con definiciones tipadas de `Field.*` y `Field.lookup(...)` para las claves - foráneas. Tú revisas y refinas; tú eres dueño del resultado. - -3. **Vincula los objetos al datasource** — por objeto, o con una regla de - enrutamiento para todo un namespace: - - ```ts - datasourceMapping: [ - { namespace: 'biz', datasource: 'business_primary' }, - { default: true, datasource: 'default' }, - ] - ``` - -4. **Deja que la IA trabaje.** En el momento en que una tabla es un objeto, la - capa de IA trabaja sobre ella de forma gratuita. Los agentes consultan a - través de ObjectQL, que enruta cada objeto a su base de datos — y cada - consulta se ejecuta como el **usuario autenticado**, obedeciendo los permisos - a nivel de objeto, de registro y de campo. - -## Por qué esto es seguro - -La objeción a "IA sobre los datos de nuestro negocio" siempre es la gobernanza, -y ahí es exactamente donde el runtime hace el trabajo: - -- **La IA actúa como el usuario, nunca por encima de él.** Un agente ve - exactamente lo que la persona detrás de él tiene permitido ver — aplicado en - el runtime, no en el prompt. -- **Solo lectura por defecto si así lo quieres.** Vincula los objetos a una - conexión o usuario de BD de solo lectura. Analiza producción de forma segura; - habilita las escrituras deliberadamente. -- **Todo auditado.** Cada lectura, escritura y escalación — humana o de agente — +Son cuatro pasos, y ninguno es "reconstruye tu app". + +### 1. Conecta la base de datos como fuente de datos + +Una fuente de datos es una conexión con nombre — Postgres, MySQL, MongoDB, +SQLite. Las credenciales vienen del entorno, nunca incrustadas en el código. +Si primero solo quieres analizar, apúntala a una réplica de lectura o a un +usuario de BD de solo lectura, y las escrituras simplemente no pueden +ocurrir. + +```ts +import type { Datasource } from '@objectstack/spec'; + +export const BusinessDb: Datasource = { + name: 'business_primary', + label: 'Business System (Postgres)', + driver: 'postgres', + config: { + connection: { + host: process.env.BIZ_DB_HOST, + user: process.env.BIZ_DB_USER, + password: process.env.BIZ_DB_PASSWORD, + database: process.env.BIZ_DB_NAME, + }, + }, + pool: { min: 1, max: 10 }, + active: true, +}; +``` + +### 2. Modela las tablas como objetos — con un agente de código + +Este es el paso que la gente espera que sea lento, y no lo es. No escribes a +mano un objeto por tabla. Apuntas un agente de código como **Claude Code** +al esquema conectado y dejas que haga la introspección y el primer borrador. +Un prompt tan simple como: + +> "Conéctate a la fuente de datos `business_primary`. Para cada una de estas +> tablas — `accounts`, `contacts`, `opportunities`, `line_items` — genera un +> archivo `src/objects/.object.ts` usando `ObjectSchema.create`. Mapea +> las columnas SQL a los tipos `Field.*` adecuados, convierte las claves +> foráneas en `Field.lookup(...)` y pon `datasource: 'business_primary'` en +> cada objeto." + +El agente lee las columnas, tipos y claves foráneas reales y escribe +archivos de objeto a nivel de código fuente. Nuestra app de referencia +[`hotcrm`](https://github.com/objectstack-ai/hotcrm) muestra la forma exacta +de esa salida: + +```ts +import { ObjectSchema, Field } from '@objectstack/spec/data'; + +export const Opportunity = ObjectSchema.create({ + name: 'biz_opportunity', + label: 'Opportunity', + datasource: 'business_primary', + fields: { + name: Field.text({ label: 'Name', required: true }), + account: Field.lookup({ label: 'Account', reference_to: 'biz_account' }), + amount: Field.currency({ label: 'Amount' }), + stage: Field.select({ label: 'Stage', options: [/* … */] }), + close_date: Field.date({ label: 'Close Date' }), + }, +}); +``` + +Como la salida es **código fuente ordinario que posees y commiteas**, +mantienes el control: conserva lo que importa, descarta las columnas que no +quieras exponer y añade encima etiquetas, validaciones y permisos. El agente +te lleva en minutos a un borrador revisable; tú lo dejas listo para +producción. + +### 3. Vincula los objetos a la fuente de datos + +Cada objeto lleva un `datasource`. Configúralo por objeto, o declara una +vez una regla de enrutamiento para todo un namespace y deja que cada objeto +bajo él la herede: + +```ts +datasourceMapping: [ + { namespace: 'biz', datasource: 'business_primary' }, + { default: true, datasource: 'default' }, +] +``` + +Las reglas coinciden por namespace, paquete o glob del nombre del objeto; +gana la primera coincidencia. Las decisiones de residencia de datos viven en +un solo lugar en vez de dispersas por los archivos. + +### 4. Deja que la IA trabaje + +En cuanto una tabla es un objeto, la capa de IA trabaja sobre ella gratis. +Los agentes y herramientas de ObjectOS — `list_objects`, `describe_object`, +`query_records`, `aggregate_data` y el agente data-chat — pasan todos por +**ObjectQL**, que enruta cada objeto a su fuente de datos vinculada y empuja +filtros, ordenaciones y agregaciones *hacia dentro de la base de datos* +cuando el driver lo soporta. + +Así que cuando un usuario pregunta: + +> "¿Qué oportunidades enterprise se cayeron del Q2, y quién las lleva?" + +el agente no vuelca la tabla entera en el prompt. Lo compila a una consulta +ObjectQL contra `biz_opportunity` — un `WHERE` sobre la etapa y la fecha de +cierre, un join al responsable — la ejecuta como `SELECT … WHERE …` en tu +Postgres y responde a partir de las filas reales y actuales. Y, lo crucial, +ejecuta esa consulta **como el usuario que ha iniciado sesión**: si un +comercial no puede ver en el CRM los deals de otra región, el agente tampoco. + +## Por qué es seguro + +La objeción a "IA sobre nuestros datos de negocio" siempre es la +gobernanza, y ahí es exactamente donde el runtime hace el trabajo: + +- **La IA actúa como el usuario, nunca por encima.** Un agente ve + precisamente lo que la persona detrás tiene permitido ver — permisos a + nivel de objeto, registro y campo, aplicados en el runtime, no en el + prompt. +- **Solo lectura por defecto si lo quieres.** Vincula los objetos a una + conexión o usuario de BD de solo lectura. Analiza producción con + seguridad; habilita las escrituras de forma deliberada, objeto a objeto. +- **Todo auditado.** Cada lectura, escritura y escalado — humano o agente — se registra con quién, qué, cuándo y por qué. -- **Tus datos permanecen en tu red.** ObjectOS se ejecuta en tu entorno. Los +- **Tus datos se quedan en tu red.** ObjectOS se ejecuta en tu entorno. Los datos de negocio y los prompts nunca salen de tu perímetro. -## Lo que ya está disponible vs. lo que viene +## Reconstruir vs. conectar + +| | Reconstruir en una nueva plataforma | Conectar con ObjectOS | +|---|---|---| +| **Tiempo hasta el primer valor** | Meses | Una tarde | +| **Riesgo para el sistema de registro** | Alto — migración, doble escritura, cambio | Ninguno — la app de origen queda intacta | +| **Dónde viven los datos** | Movidos | Se quedan justo donde están | +| **Esfuerzo de modelado** | Reimplementar cada entidad a mano | El agente redacta objetos desde el esquema vivo | +| **Permisos** | Reconstruidos y reauditados | Heredados; la IA obedece el mismo modelo | +| **Reversibilidad** | Difícil de deshacer | Desconecta la fuente — nada cambió | + +## Lo que obtienes el primer día + +Una vez que un puñado de tablas está modelado y vinculado: + +- **Análisis en lenguaje natural** sobre registros en vivo, calculado a + través de ObjectQL — no una exportación obsoleta. +- **Automatización gobernada.** Flujos y acciones leen y (donde se permite) + escriben los mismos datos, con cada paso auditado. +- **Una API y una Consola generadas.** Los endpoints REST/GraphQL y las + pantallas de administración salen de los mismos metadatos — sin capa de + integración extra. +- **Un único modelo de permisos.** La frontera que aplica a los humanos + aplica idéntica al tráfico de IA. + +## Lo entregado vs. lo que viene + +El flujo anterior funciona **hoy** con bloques ya entregados: fuentes de +datos, enrutamiento por objeto, pushdown de ObjectQL consciente de +capacidades y la capa de agentes de IA. El modelado de objetos se hace con +un agente de código contra tu esquema conectado — igual que se escribieron +los objetos de `hotcrm`. + +Una experiencia de **federación llave en mano** más rica — importación de +esquema en un paso, vinculación a esquemas de propiedad externa y puertas de +seguridad de escritura integradas — está en diseño activo bajo +[ADR-0015](https://github.com/objectstack-ai/framework/blob/main/docs/adr/0015-external-datasource-federation.md) +(estado: *Proposed*). Escribiremos más a medida que llegue. Hasta entonces, +el camino documentado — conectar, modelar, vincular, consultar — es el +soportado. -El flujo anterior funciona **hoy** con bloques de construcción ya disponibles: -datasources, enrutamiento por objeto, pushdown de ObjectQL consciente de -capacidades y la capa de agentes de IA. La generación de objetos se hace con un -agente de programación contra tu esquema conectado — de la misma forma en que se -crearon los objetos de `hotcrm`. +## Preguntas frecuentes -Una experiencia de **federación llave en mano** más completa — importación de -esquema en un solo paso, vinculación a esquemas de propiedad externa y -compuertas de seguridad de escritura integradas — está en diseño activo bajo -[ADR-0015](https://github.com/objectstack-ai/framework/blob/main/docs/adr/0015-external-datasource-federation.md) -(estado: *Propuesto*). Escribiremos más a medida que se materialice. Hasta -entonces, el camino documentado es el camino soportado. +**¿Tengo que modelar todas las tablas?** No. Modela solo las tablas que +quieras que la IA y la automatización toquen. El resto de la base de datos se +ignora. + +**¿Esto escribirá en mi base de datos de producción?** Solo si lo permites. +Vincula a una conexión o usuario de BD de solo lectura y las escrituras son +imposibles; habilítalas de forma deliberada, por objeto, cuando estés listo. + +**¿Mis datos van a un proveedor de modelos?** ObjectOS se ejecuta en tu +entorno y las consultas corren contra tu base de datos. Tú controlas qué +proveedor de IA se configura y qué puede ver. + +**¿Y si cambia mi esquema?** Vuelve a ejecutar el agente de código contra el +esquema actualizado para regenerar o hacer diff de los objetos afectados — +son solo archivos de código en tu repo. ## Pruébalo -- [Data Sources](/docs/configure/data-sources) — la guía completa de creación -- [Extend Existing Systems](/docs/extend-existing-systems) — el escenario, de principio a fin -- [AI Agents](/docs/build/agents) — agentes declarativos sobre tus objetos +- [Fuentes de datos](/docs/configure/data-sources) — la guía completa de + autoría +- [Extiende sistemas existentes](/docs/extend-existing-systems) — el + escenario, de principio a fin +- [Agentes de IA](/docs/build/agents) — agentes declarativos sobre tus + objetos -Si ya tienes una base de datos de negocio, estás a buena parte del camino. -Conéctala, modela unas cuantas tablas y hazle una pregunta a tus datos. +Si ya tienes una base de datos de negocio, ya tienes casi todo el camino +hecho. Conéctala, modela unas tablas y hazle una pregunta a tus datos. diff --git a/content/blog/extend-existing-systems-with-ai.fr.mdx b/content/blog/extend-existing-systems-with-ai.fr.mdx index 8f894d0..ce1708f 100644 --- a/content/blog/extend-existing-systems-with-ai.fr.mdx +++ b/content/blog/extend-existing-systems-with-ai.fr.mdx @@ -1,6 +1,6 @@ --- title: "Rendez votre système métier existant AI-native — sans migration" -description: "Connectez ObjectOS à la base de données que vous exploitez déjà, modélisez les tables comme des objets, et laissez l'IA interroger et agir sur des données réelles — sous vos permissions, sur vos serveurs." +description: "Connectez ObjectOS à la base de données que vous exploitez déjà, laissez un agent de code modéliser les tables en objets et posez l'IA sur des données réelles — sous vos permissions, sur vos serveurs, sans toucher au système d'origine." author: ObjectStack Team date: 2026-05-30 tags: @@ -9,122 +9,248 @@ tags: - Architecture --- -La plupart des argumentaires « ajoutez de l'IA à votre activité » -présupposent discrètement une reconstruction : transférer les données -vers une nouvelle plateforme, réimplémenter les workflows, reformer -l'équipe. C'est précisément la partie dont personne ne veut. Le système -de référence — le CRM, l'ERP, l'outil de ticketing, le back-office maison -— fonctionne déjà, et c'est déjà là que vivent les données. +La plupart des discours « ajoutez de l'IA à votre métier » présupposent en +douce une reconstruction : déplacer les données vers une nouvelle +plateforme, réimplémenter les workflows, reformer l'équipe et prier pour que +la migration aboutisse. C'est la part dont personne ne veut. Le système de +référence — le CRM, l'ERP, l'outil de tickets, le back-office maison — +fonctionne déjà, et les données sont déjà là. -ObjectOS adopte la position inverse. **Vous ne migrez pas. Vous -connectez.** +ObjectOS adopte la posture inverse. **Vous ne migrez pas. Vous connectez.** ## L'idée en une phrase -Pointez ObjectOS vers votre base de données existante, décrivez comme des -objets les tables qui vous intéressent, et chaque agent IA, flux et -tableau de bord fonctionne immédiatement sur ces données — routé -automatiquement vers le bon système, gouverné par les mêmes permissions -que vos utilisateurs possèdent déjà. - -L'application d'origine ne change pas. Les lignes ne bougent pas. -ObjectOS devient la surface AI-native et sensible aux permissions -au-dessus de ce que vous exploitez déjà. - -## Comment cela fonctionne aujourd'hui - -Il y a quatre étapes, et aucune d'elles n'est « reconstruire votre -application » : - -1. **Connectez la base de données comme datasource.** Une datasource est - une connexion nommée — Postgres, MySQL, MongoDB, SQLite. Les - identifiants proviennent de l'environnement, et la connexion peut être - en lecture seule si vous voulez d'abord vous contenter d'analyser. - - ```ts - import type { Datasource } from '@objectstack/spec'; - - export const BusinessDb: Datasource = { - name: 'business_primary', - label: 'Business System (Postgres)', - driver: 'postgres', - config: { - connection: { - host: process.env.BIZ_DB_HOST, - user: process.env.BIZ_DB_USER, - password: process.env.BIZ_DB_PASSWORD, - database: process.env.BIZ_DB_NAME, - }, - }, - active: true, - }; - ``` - -2. **Modélisez les tables comme des objets** — et vous n'avez pas à les - saisir à la main. Pointez un agent de codage comme Claude Code vers le - schéma connecté et demandez-lui de générer un fichier objet au niveau - source par table. Notre application de référence - [`hotcrm`](https://github.com/objectstack-ai/hotcrm) montre la forme - exacte que prend cette sortie : un `ObjectSchema.create({ … })` avec - des définitions `Field.*` typées et `Field.lookup(...)` pour les clés - étrangères. Vous révisez et affinez ; le résultat vous appartient. - -3. **Liez les objets à la datasource** — par objet, ou avec une règle de - routage pour tout un namespace : - - ```ts - datasourceMapping: [ - { namespace: 'biz', datasource: 'business_primary' }, - { default: true, datasource: 'default' }, - ] - ``` - -4. **Laissez l'IA travailler.** Dès qu'une table est un objet, la couche - IA travaille dessus gratuitement. Les agents interrogent via ObjectQL, - qui route chaque objet vers sa base de données — et chaque requête - s'exécute en tant qu'**utilisateur connecté**, en respectant les - permissions au niveau objet, enregistrement et champ. +Pointez ObjectOS vers votre base de données existante, décrivez en objets +les tables qui vous importent, et chaque agent IA, flux, API et tableau de +bord travaille immédiatement sur ces données — routées automatiquement vers +le bon système et gouvernées par les mêmes permissions que vos utilisateurs +ont déjà. + +L'application d'origine ne change pas. Les lignes ne bougent pas. ObjectOS +devient la surface AI-native et consciente des permissions par-dessus ce que +vous exploitez déjà. + +## Une image concrète + +Disons que votre équipe commerciale tourne sur un CRM Postgres de 40 tables. +Comptes, contacts, opportunités, lignes de commande, activités — des années +de données réelles, une application en production que vos commerciaux +utilisent chaque jour. La direction veut deux choses : que les gens puissent +*interroger* ces données en langage naturel (« quelles affaires enterprise +ont glissé hors du T2, et qui les porte ? ») et que les automatisations +agissent dessus en toute sécurité. + +La réponse « reconstruction » est un projet de six mois. La réponse ObjectOS +est une après-midi : + +1. Connecter la base du CRM comme source de données en **lecture seule**. +2. Faire modéliser en objets, par un agent de code, la douzaine de tables qui + vous importent vraiment. +3. Poser des questions à vos données et câbler la première automatisation. + +Personne ne touche au CRM. Les commerciaux n'y voient rien. Vous obtenez une +couche AI-native sur exactement les mêmes lignes. + +## Comment ça marche aujourd'hui + +Quatre étapes, et aucune n'est « reconstruisez votre app ». + +### 1. Connecter la base comme source de données + +Une source de données est une connexion nommée — Postgres, MySQL, MongoDB, +SQLite. Les identifiants viennent de l'environnement, jamais en dur dans le +code. Si vous voulez d'abord juste analyser, pointez-la vers un réplica en +lecture ou un utilisateur de BD en lecture seule, et les écritures ne +peuvent tout simplement pas se produire. + +```ts +import type { Datasource } from '@objectstack/spec'; + +export const BusinessDb: Datasource = { + name: 'business_primary', + label: 'Business System (Postgres)', + driver: 'postgres', + config: { + connection: { + host: process.env.BIZ_DB_HOST, + user: process.env.BIZ_DB_USER, + password: process.env.BIZ_DB_PASSWORD, + database: process.env.BIZ_DB_NAME, + }, + }, + pool: { min: 1, max: 10 }, + active: true, +}; +``` + +### 2. Modéliser les tables en objets — avec un agent de code + +C'est l'étape que tout le monde s'attend à voir lente, et elle ne l'est pas. +Vous ne tapez pas un objet par table à la main. Vous pointez un agent de code +comme **Claude Code** vers le schéma connecté et le laissez faire +l'introspection et le premier jet. Une consigne aussi simple que : + +> « Connecte-toi à la source de données `business_primary`. Pour chacune de +> ces tables — `accounts`, `contacts`, `opportunities`, `line_items` — +> génère un fichier `src/objects/.object.ts` avec +> `ObjectSchema.create`. Mappe les colonnes SQL vers les bons types +> `Field.*`, transforme les clés étrangères en `Field.lookup(...)` et mets +> `datasource: 'business_primary'` sur chaque objet. » + +L'agent lit les vraies colonnes, types et clés étrangères et écrit des +fichiers d'objet au niveau du code source. Notre application de référence +[`hotcrm`](https://github.com/objectstack-ai/hotcrm) montre la forme exacte +de cette sortie : + +```ts +import { ObjectSchema, Field } from '@objectstack/spec/data'; + +export const Opportunity = ObjectSchema.create({ + name: 'biz_opportunity', + label: 'Opportunity', + datasource: 'business_primary', + fields: { + name: Field.text({ label: 'Name', required: true }), + account: Field.lookup({ label: 'Account', reference_to: 'biz_account' }), + amount: Field.currency({ label: 'Amount' }), + stage: Field.select({ label: 'Stage', options: [/* … */] }), + close_date: Field.date({ label: 'Close Date' }), + }, +}); +``` + +Parce que la sortie est **du code source ordinaire que vous possédez et +commitez**, vous gardez le contrôle : conservez ce qui compte, écartez les +colonnes que vous ne voulez pas exposer, et ajoutez par-dessus libellés, +validations et permissions. L'agent vous amène en quelques minutes à un jet +relisible ; à vous de le rendre prêt pour la production. + +### 3. Lier les objets à la source de données + +Chaque objet porte un `datasource`. Réglez-le par objet, ou déclarez une fois +une règle de routage pour tout un namespace et laissez chaque objet en +dessous en hériter : + +```ts +datasourceMapping: [ + { namespace: 'biz', datasource: 'business_primary' }, + { default: true, datasource: 'default' }, +] +``` + +Les règles correspondent par namespace, paquet ou glob de nom d'objet ; la +première correspondance gagne. Les décisions de résidence des données vivent +à un seul endroit au lieu d'être éparpillées dans les fichiers. + +### 4. Laisser l'IA travailler + +Dès qu'une table est un objet, la couche IA travaille dessus gratuitement. +Les agents et outils d'ObjectOS — `list_objects`, `describe_object`, +`query_records`, `aggregate_data` et l'agent data-chat — passent tous par +**ObjectQL**, qui route chaque objet vers sa source de données liée et pousse +filtres, tris et agrégations *dans la base de données* lorsque le driver le +supporte. + +Ainsi, quand un utilisateur demande : + +> « Quelles opportunités enterprise ont glissé hors du T2, et qui les +> porte ? » + +l'agent ne déverse pas la table entière dans le prompt. Il compile cela en +une requête ObjectQL contre `biz_opportunity` — un `WHERE` sur l'étape et la +date de clôture, une jointure vers le responsable — l'exécute en +`SELECT … WHERE …` sur votre Postgres et répond à partir des lignes réelles +et actuelles. Et surtout, il exécute cette requête **en tant qu'utilisateur +connecté** : si un commercial ne peut pas voir dans le CRM les affaires d'une +autre région, l'agent non plus. ## Pourquoi c'est sûr L'objection à « de l'IA sur nos données métier » est toujours la gouvernance, et c'est exactement là que le runtime fait le travail : -- **L'IA agit en tant qu'utilisateur, jamais au-dessus de lui.** Un agent - voit précisément ce que la personne derrière lui est autorisée à voir — - appliqué dans le runtime, pas dans le prompt. -- **Lecture seule par défaut si vous le souhaitez.** Liez les objets à - une connexion ou un utilisateur de base de données en lecture seule. - Analysez la production en toute sécurité ; activez les écritures - délibérément. -- **Tout est audité.** Chaque lecture, écriture et escalade — humaine ou +- **L'IA agit comme l'utilisateur, jamais au-dessus de lui.** Un agent voit + précisément ce que la personne derrière a le droit de voir — permissions au + niveau objet, enregistrement et champ, appliquées dans le runtime, pas dans + le prompt. +- **En lecture seule par défaut si vous le voulez.** Liez les objets à une + connexion ou un utilisateur de BD en lecture seule. Analysez la production + en sécurité ; activez les écritures délibérément, objet par objet. +- **Tout est audité.** Chaque lecture, écriture et élévation — humaine ou agent — est enregistrée avec qui, quoi, quand et pourquoi. -- **Vos données restent dans votre réseau.** ObjectOS s'exécute dans - votre environnement. Les données métier et les prompts ne quittent - jamais votre périmètre. +- **Vos données restent dans votre réseau.** ObjectOS s'exécute dans votre + environnement. Les données métier et les prompts ne quittent jamais votre + périmètre. + +## Reconstruire vs. connecter -## Ce qui est livré vs. ce qui arrive +| | Reconstruire sur une nouvelle plateforme | Connecter avec ObjectOS | +|---|---|---| +| **Délai avant la première valeur** | Des mois | Une après-midi | +| **Risque pour le système de référence** | Élevé — migration, double écriture, bascule | Nul — l'app source reste intacte | +| **Où vivent les données** | Déplacées | Restent exactement où elles sont | +| **Effort de modélisation** | Réimplémenter chaque entité à la main | L'agent rédige les objets depuis le schéma vivant | +| **Permissions** | Reconstruites et réauditées | Héritées ; l'IA obéit au même modèle | +| **Réversibilité** | Difficile à défaire | Déconnectez la source — rien n'a changé | -Le flux ci-dessus fonctionne **aujourd'hui** avec des briques déjà -livrées : datasources, routage par objet, pushdown ObjectQL sensible aux -capacités, et la couche d'agents IA. La génération des objets se fait avec -un agent de codage sur votre schéma connecté — de la même manière que les -objets `hotcrm` ont été rédigés. +## Ce que vous obtenez dès le premier jour -Une expérience de **fédération clé en main** plus riche — import de schéma -en une étape, liaison à des schémas détenus en externe et garde-fous -d'écriture intégrés — est en cours de conception sous +Une fois qu'une poignée de tables est modélisée et liée : + +- **Analyse en langage naturel** sur des enregistrements en direct, calculée + via ObjectQL — pas un export périmé. +- **Automatisation gouvernée.** Les flux et actions lisent et (là où c'est + permis) écrivent les mêmes données, chaque étape étant auditée. +- **Une API et une Console générées.** Les endpoints REST/GraphQL et les + écrans d'admin sortent des mêmes métadonnées — pas de couche d'intégration + supplémentaire. +- **Un seul modèle de permissions.** La frontière qui s'applique aux humains + s'applique à l'identique au trafic IA. + +## Livré vs. à venir + +Le flux ci-dessus fonctionne **aujourd'hui** avec des briques déjà livrées : +sources de données, routage par objet, pushdown ObjectQL conscient des +capacités et couche d'agents IA. La modélisation des objets se fait avec un +agent de code contre votre schéma connecté — exactement comme les objets de +`hotcrm` ont été écrits. + +Une expérience de **fédération clé en main** plus riche — import de schéma en +une étape, liaison à des schémas détenus en externe et garde-fous d'écriture +intégrés — est en conception active sous [ADR-0015](https://github.com/objectstack-ai/framework/blob/main/docs/adr/0015-external-datasource-federation.md) -(statut : *Proposé*). Nous en écrirons davantage à mesure que cela se -concrétisera. D'ici là, le chemin documenté est celui qui est pris en -charge. +(statut : *Proposed*). Nous en écrirons davantage à mesure qu'elle arrive. +D'ici là, le chemin documenté — connecter, modéliser, lier, interroger — est +celui pris en charge. + +## Questions fréquentes + +**Dois-je modéliser toutes les tables ?** Non. Ne modélisez que les tables +que vous voulez que l'IA et l'automatisation touchent. Le reste de la base +est ignoré. + +**Est-ce que cela va écrire dans ma base de production ?** Seulement si vous +l'autorisez. Liez à une connexion ou un utilisateur de BD en lecture seule et +les écritures sont impossibles ; activez-les délibérément, par objet, quand +vous êtes prêt. + +**Mes données partent-elles vers un fournisseur de modèle ?** ObjectOS +s'exécute dans votre environnement et les requêtes tournent contre votre base +de données. Vous contrôlez quel fournisseur d'IA est configuré et ce qu'il a +le droit de voir. + +**Et si mon schéma change ?** Relancez l'agent de code contre le schéma mis à +jour pour régénérer ou comparer les objets concernés — ce ne sont que des +fichiers source dans votre dépôt. -## Essayez-le +## Essayez -- [Data Sources](/docs/configure/data-sources) — le guide de rédaction complet -- [Étendre les systèmes existants](/docs/extend-existing-systems) — le scénario, de bout en bout +- [Sources de données](/docs/configure/data-sources) — le guide d'auteur + complet +- [Étendre les systèmes existants](/docs/extend-existing-systems) — le + scénario de bout en bout - [Agents IA](/docs/build/agents) — des agents déclaratifs sur vos objets -Si vous disposez déjà d'une base de données métier, vous êtes presque -arrivé. Connectez-la, modélisez quelques tables, et posez une question à -vos données. +Si vous avez déjà une base de données métier, vous avez fait l'essentiel du +chemin. Connectez-la, modélisez quelques tables et posez une question à vos +données. diff --git a/content/blog/extend-existing-systems-with-ai.ja.mdx b/content/blog/extend-existing-systems-with-ai.ja.mdx index 4ccbf0c..b618146 100644 --- a/content/blog/extend-existing-systems-with-ai.ja.mdx +++ b/content/blog/extend-existing-systems-with-ai.ja.mdx @@ -1,6 +1,6 @@ --- -title: "既存の業務システムを移行なしで AI ネイティブにする" -description: "ObjectOS をすでに稼働しているデータベースに接続し、テーブルをオブジェクトとしてモデル化すれば、AI が実データをクエリし操作できます — あなたの権限のもとで、あなたのサーバー上で。" +title: "既存の業務システムを、移行なしで AI ネイティブにする" +description: "すでに稼働しているデータベースに ObjectOS を接続し、コーディングエージェントにテーブルをオブジェクトとしてモデリングさせ、実データに AI を載せる —— あなたの権限のもと、あなたのサーバー上で、元のシステムには一切手を触れずに。" author: ObjectStack Team date: 2026-05-30 tags: @@ -9,109 +9,227 @@ tags: - Architecture --- -「業務に AI を追加しましょう」という売り込みのほとんどは、暗黙のうちに作り直しを -前提としています。データを新しいプラットフォームに移し、ワークフローを再実装し、 -チームを再教育する。それこそ誰もやりたくない部分です。システムオブレコード — CRM、 -ERP、チケット管理ツール、内製のバックオフィス — はすでに動いており、データもすでに -そこにあります。 +「業務に AI を追加しよう」という多くの売り文句は、こっそり再構築を前提に +しています。データを新しいプラットフォームへ移し、ワークフローを作り直し、 +チームを再教育し、移行が成功するよう祈る。誰もやりたくない部分です。記録 +システム —— CRM、ERP、チケットツール、自作のバックオフィス —— はすでに +動いていて、データもすでにそこにあります。 -ObjectOS は正反対の立場を取ります。**移行はしません。接続するのです。** +ObjectOS は逆の立場を取ります。**移行しない。接続する。** ## 一文で言うと ObjectOS を既存のデータベースに向け、関心のあるテーブルをオブジェクトとして -記述すれば、あらゆる AI エージェント、フロー、ダッシュボードが即座にそのデータ上で -動作します — 適切なシステムへ自動的にルーティングされ、ユーザーがすでに持っている -権限と同じものによって統制されます。 - -元のアプリケーションは変わりません。レコードは動きません。ObjectOS は、あなたが -すでに稼働しているものの上に乗る、AI ネイティブで権限を認識するサーフェスになります。 - -## 現状の仕組み - -手順は 4 つあり、そのどれもが「アプリを作り直す」ものではありません。 - -1. **データベースをデータソースとして接続する。** データソースとは名前付きの - 接続です — Postgres、MySQL、MongoDB、SQLite。認証情報は環境から取得され、 - まず分析だけしたい場合は接続を読み取り専用にできます。 - - ```ts - import type { Datasource } from '@objectstack/spec'; - - export const BusinessDb: Datasource = { - name: 'business_primary', - label: 'Business System (Postgres)', - driver: 'postgres', - config: { - connection: { - host: process.env.BIZ_DB_HOST, - user: process.env.BIZ_DB_USER, - password: process.env.BIZ_DB_PASSWORD, - database: process.env.BIZ_DB_NAME, - }, - }, - active: true, - }; - ``` - -2. **テーブルをオブジェクトとしてモデル化する** — しかも手で入力する必要は - ありません。Claude Code のようなコーディングエージェントを接続済みのスキーマに - 向け、テーブルごとに 1 つのソースレベルのオブジェクトファイルを生成するよう - 依頼してください。私たちの - [`hotcrm`](https://github.com/objectstack-ai/hotcrm) リファレンスアプリは、 - その出力が取る正確なかたちを示しています。型付けされた `Field.*` 定義と外部キー用の - `Field.lookup(...)` を備えた `ObjectSchema.create({ … })` です。あなたはレビューして - 洗練させ、その結果を所有します。 - -3. **オブジェクトをデータソースに紐付ける** — オブジェクトごとに、あるいは - 名前空間全体に対するルーティングルールで: - - ```ts - datasourceMapping: [ - { namespace: 'biz', datasource: 'business_primary' }, - { default: true, datasource: 'default' }, - ] - ``` - -4. **AI に働かせる。** テーブルがオブジェクトになった瞬間、AI レイヤーは追加コスト - なしでその上で動作します。エージェントは ObjectQL を介してクエリし、ObjectQL は各 - オブジェクトをそのデータベースへルーティングします — そしてすべてのクエリは - **サインイン済みユーザー** として実行され、オブジェクトレベル、レコードレベル、 - フィールドレベルの権限に従います。 +記述すれば、すべての AI エージェント、フロー、API、ダッシュボードが即座に +そのデータ上で動きます —— 適切なシステムへ自動的にルーティングされ、ユーザーが +すでに持っているのと同じ権限で統制されます。 + +元のアプリケーションは変わりません。行は移動しません。ObjectOS は、すでに +動いているものの上に乗る、AI ネイティブで権限を意識したレイヤーになります。 + +## 具体的なイメージ + +40 テーブルの Postgres CRM で営業チームを回しているとしましょう。アカウント、 +コンタクト、商談、明細行、活動 —— 何年分もの実データ、担当者が毎日使う本番 +アプリです。経営陣が望むのは 2 つ。データに自然言語で*質問できる*こと +（「Q2 から滑り落ちたエンタープライズ商談はどれで、誰が担当か？」）と、 +自動化が安全にそのデータを操作できることです。 + +再構築の答えは 6 か月のプロジェクト。ObjectOS の答えは午後ひとつです。 + +1. CRM データベースを**読み取り専用**のデータソースとして接続する。 +2. 本当に関心のある十数個のテーブルを、コーディングエージェントにオブジェクト + としてモデリングさせる。 +3. データに質問し、最初の自動化を組む。 + +誰も CRM に触れません。担当者は気づきもしません。それでいて、まったく同じ +行の上に AI ネイティブなレイヤーが手に入ります。 + +## 今日どう動くか + +4 ステップで、どれも「アプリを作り直す」ではありません。 + +### 1. データベースをデータソースとして接続する + +データソースは名前付きの接続です —— Postgres、MySQL、MongoDB、SQLite。 +認証情報は環境変数から取得し、ソースに直書きしません。まず分析だけしたい +なら、リードレプリカや読み取り専用 DB ユーザーに向ければ、書き込みは +そもそも起こり得ません。 + +```ts +import type { Datasource } from '@objectstack/spec'; + +export const BusinessDb: Datasource = { + name: 'business_primary', + label: 'Business System (Postgres)', + driver: 'postgres', + config: { + connection: { + host: process.env.BIZ_DB_HOST, + user: process.env.BIZ_DB_USER, + password: process.env.BIZ_DB_PASSWORD, + database: process.env.BIZ_DB_NAME, + }, + }, + pool: { min: 1, max: 10 }, + active: true, +}; +``` + +### 2. テーブルをオブジェクトにモデリングする —— コーディングエージェントで + +遅いと思われがちな工程ですが、そうではありません。テーブルごとにオブジェクトを +手書きする必要はありません。**Claude Code** のようなコーディングエージェントを +接続済みスキーマに向け、内省と初稿を任せます。次のような素朴なプロンプトで +十分です。 + +> 「`business_primary` データソースに接続して。`accounts`、`contacts`、 +> `opportunities`、`line_items` の各テーブルについて、`ObjectSchema.create` +> を使った `src/objects/.object.ts` を 1 ファイルずつ生成して。SQL の +> カラムを適切な `Field.*` 型にマッピングし、外部キーは `Field.lookup(...)` +> にして、各オブジェクトに `datasource: 'business_primary'` を設定して。」 + +エージェントは実際のカラム、型、外部キーを読み取り、ソースレベルのオブジェクト +ファイルを書き出します。私たちの +[`hotcrm`](https://github.com/objectstack-ai/hotcrm) リファレンスアプリが、 +その出力の正確な形を示しています。 + +```ts +import { ObjectSchema, Field } from '@objectstack/spec/data'; + +export const Opportunity = ObjectSchema.create({ + name: 'biz_opportunity', + label: 'Opportunity', + datasource: 'business_primary', + fields: { + name: Field.text({ label: 'Name', required: true }), + account: Field.lookup({ label: 'Account', reference_to: 'biz_account' }), + amount: Field.currency({ label: 'Amount' }), + stage: Field.select({ label: 'Stage', options: [/* … */] }), + close_date: Field.date({ label: 'Close Date' }), + }, +}); +``` + +出力は**あなたが所有しコミットする普通のソース**なので、主導権は常にあなたに +あります。必要なカラムは残し、公開したくないものは外し、ラベル・バリデーション・ +権限を重ねます。エージェントは数分でレビュー可能な初稿まで連れて行き、本番品質に +仕上げるのはあなたです。 + +### 3. オブジェクトをデータソースにバインドする + +各オブジェクトは `datasource` を持ちます。オブジェクトごとに設定するか、 +名前空間全体に対して一度ルーティングルールを宣言し、その下のオブジェクトに +継承させます。 + +```ts +datasourceMapping: [ + { namespace: 'biz', datasource: 'business_primary' }, + { default: true, datasource: 'default' }, +] +``` + +ルールは名前空間、パッケージ、オブジェクト名の glob でマッチし、最初に一致した +ものが勝ちます。データの所在に関する判断が、ファイルに散らばらず一か所に +まとまります。 + +### 4. AI に働かせる + +テーブルがオブジェクトになった瞬間、AI レイヤーはそれを無償で扱えます。 +ObjectOS のエージェントとツール —— `list_objects`、`describe_object`、 +`query_records`、`aggregate_data`、そして data-chat エージェント —— はすべて +**ObjectQL** を通り、各オブジェクトをバインド先のデータソースへルーティングし、 +ドライバーが対応していればフィルタ・ソート・集計を*データベースへプッシュダウン* +します。 + +そこでユーザーがこう尋ねると: + +> 「Q2 から滑り落ちたエンタープライズ商談はどれで、誰が担当か？」 + +エージェントはテーブル全体をプロンプトに流し込みません。これを +`biz_opportunity` に対する ObjectQL クエリ —— ステージとクローズ日への +`WHERE`、担当者への join —— にコンパイルし、あなたの Postgres 上で +`SELECT … WHERE …` として実行し、実際の最新の行から回答します。そして +決定的なのは、それを**サインイン中のユーザー**として実行する点です。ある担当者が +CRM で他リージョンの商談を見られないなら、エージェントも見られません。 ## なぜ安全なのか -「私たちの業務データに AI を」という反論は常にガバナンスに行き着きますが、まさに +「自社の業務データに AI を載せる」ことへの懸念は常にガバナンスであり、まさに そこをランタイムが担います。 -- **AI はユーザーとして振る舞い、決してその上には立たない。** エージェントは、その - 背後にいる人が見ることを許されているものだけを正確に見ます — プロンプトではなく - ランタイムで強制されます。 -- **必要なら既定で読み取り専用。** オブジェクトを読み取り専用の接続または DB ユーザーに - 紐付けてください。本番を安全に分析し、書き込みは意図的に有効化します。 -- **すべてが監査される。** すべての読み取り、書き込み、権限昇格は — 人間でも - エージェントでも — 誰が、何を、いつ、なぜ行ったかとともに記録されます。 -- **データはあなたのネットワーク内にとどまる。** ObjectOS はあなたの環境で動作します。 - 業務データとプロンプトがあなたの境界の外に出ることはありません。 - -## 出荷済みのもの vs. これから来るもの - -上記のフローは、出荷済みのビルディングブロックで **今日** 動作します。データソース、 -オブジェクトごとのルーティング、機能を認識する ObjectQL のプッシュダウン、そして AI -エージェントレイヤーです。オブジェクトの生成は、接続済みのスキーマに対してコーディング -エージェントで行われます — `hotcrm` のオブジェクトが書かれたのと同じ方法です。 - -よりリッチな **ターンキーのフェデレーション** 体験 — ワンステップのスキーマ -インポート、外部所有スキーマへの紐付け、組み込みの書き込み安全ゲート — は +- **AI はユーザーとして動き、決して上位には立たない。** エージェントが見るのは、 + その背後にいる人物が見ることを許された範囲とぴったり同じ —— オブジェクト・ + レコード・フィールドレベルの権限を、プロンプトではなくランタイムが強制します。 +- **望むなら既定で読み取り専用。** オブジェクトを読み取り専用の接続や DB ユーザーに + バインドします。本番を安全に分析し、書き込みは意図的に、オブジェクト単位で + 有効化します。 +- **すべて監査される。** 読み取り・書き込み・権限昇格はいずれも —— 人でも + エージェントでも —— 誰が・何を・いつ・なぜ、として記録されます。 +- **データは自社ネットワークに留まる。** ObjectOS はあなたの環境で動きます。 + 業務データもプロンプトも境界の外には出ません。 + +## 再構築 vs. 接続 + +| | 新プラットフォームへ再構築 | ObjectOS で接続 | +|---|---|---| +| **価値が出るまでの時間** | 数か月 | 午後ひとつ | +| **記録システムへのリスク** | 高 —— データ移行、二重書き込み、切り替え | なし —— 元アプリは無傷 | +| **データの所在** | 移動する | そのまま | +| **モデリング工数** | 各エンティティを手作業で再実装 | エージェントが実スキーマから起草 | +| **権限** | 再構築・再監査 | 継承。AI は同じモデルに従う | +| **可逆性** | 元に戻しにくい | データソースを切断 —— 何も変わっていない | + +## 初日に手に入るもの + +数個のテーブルをモデリングしてバインドすれば: + +- **自然言語による分析**が、ライブのレコードに対し ObjectQL で計算されます —— + 古いエクスポートではなく。 +- **統制された自動化。** フローとアクションが同じデータを読み、（許可された範囲で） + 書き込み、各ステップが監査されます。 +- **生成された API とコンソール。** REST/GraphQL のエンドポイントと管理画面が + 同じメタデータから生まれます —— 追加の連携層は不要です。 +- **単一の権限モデル。** 人に適用される境界が、AI のトラフィックにも等しく + 適用されます。 + +## 出荷済み vs. これから + +上記のフローは、出荷済みのビルディングブロック —— データソース、オブジェクト単位 +のルーティング、能力を意識した ObjectQL のプッシュダウン、AI エージェント層 —— +で**今日**動きます。オブジェクトのモデリングは、接続済みスキーマに対して +コーディングエージェントが行います —— `hotcrm` のオブジェクトが書かれたのと +同じやり方です。 + +より充実した**ターンキーなフェデレーション** —— ワンステップのスキーマ取り込み、 +外部所有スキーマへのバインド、組み込みの書き込み安全ゲート —— は [ADR-0015](https://github.com/objectstack-ai/framework/blob/main/docs/adr/0015-external-datasource-federation.md) -のもとで活発に設計中です（ステータス: *Proposed*）。実装が進み次第、より詳しく -書きます。それまでは、ドキュメント化された経路がサポート対象です。 +（ステータス: *Proposed*）のもとで活発に設計中です。実装が進めば追って書きます。 +それまでは、文書化された道 —— 接続、モデリング、バインド、クエリ —— がサポート +対象です。 + +## よくある質問 + +**すべてのテーブルをモデリングする必要は？** ありません。AI や自動化に触れさせたい +テーブルだけをモデリングします。残りのデータベースは無視されます。 + +**本番データベースに書き込まれますか？** あなたが許可した場合だけです。読み取り +専用の接続や DB ユーザーにバインドすれば書き込みは不可能で、準備ができたら +オブジェクト単位で意図的に有効化します。 + +**データはモデルプロバイダーに送られますか？** ObjectOS はあなたの環境で動き、 +クエリはあなたのデータベースで実行されます。どの AI プロバイダーを設定し、何を +見せるかはあなたが管理します。 + +**スキーマが変わったら？** 更新後のスキーマに対してコーディングエージェントを +再実行し、影響を受けたオブジェクトを再生成または差分します —— それらはリポジトリ内の +ただのソースファイルです。 ## 試してみる -- [Data Sources](/docs/configure/data-sources) — 完全な作成ガイド -- [Extend Existing Systems](/docs/extend-existing-systems) — シナリオ全体を端から端まで -- [AI Agents](/docs/build/agents) — あなたのオブジェクト上の宣言的エージェント +- [データソース](/docs/configure/data-sources) —— 完全な作成ガイド +- [既存システムの拡張](/docs/extend-existing-systems) —— エンドツーエンドのシナリオ +- [AI エージェント](/docs/build/agents) —— オブジェクト上の宣言的エージェント -すでに業務データベースをお持ちなら、もうほとんど準備は整っています。接続し、 -いくつかのテーブルをモデル化し、あなたのデータに問いかけてみてください。 +すでに業務データベースをお持ちなら、ほぼゴール目前です。接続し、いくつかの +テーブルをモデリングし、データに質問してみてください。 diff --git a/content/blog/extend-existing-systems-with-ai.ko.mdx b/content/blog/extend-existing-systems-with-ai.ko.mdx index e7d0153..56e6353 100644 --- a/content/blog/extend-existing-systems-with-ai.ko.mdx +++ b/content/blog/extend-existing-systems-with-ai.ko.mdx @@ -1,6 +1,6 @@ --- title: "마이그레이션 없이 기존 비즈니스 시스템을 AI 네이티브로 만들기" -description: "이미 운영 중인 데이터베이스에 ObjectOS를 연결하고, 테이블을 객체로 모델링하면, AI가 실제 데이터를 조회하고 작동하게 됩니다 — 여러분의 권한 아래, 여러분의 서버에서." +description: "이미 운영 중인 데이터베이스에 ObjectOS를 연결하고, 코딩 에이전트가 테이블을 객체로 모델링하게 한 뒤, 실제 데이터 위에 AI를 올리세요 — 여러분의 권한 아래, 여러분의 서버에서, 원래 시스템은 그대로 둔 채." author: ObjectStack Team date: 2026-05-30 tags: @@ -9,113 +9,222 @@ tags: - Architecture --- -대부분의 "비즈니스에 AI를 더하세요"라는 제안은 은근히 재구축을 전제로 -합니다. 데이터를 새 플랫폼으로 옮기고, 워크플로우를 다시 구현하고, 팀을 -재교육합니다. 바로 그 부분을 아무도 원하지 않습니다. 시스템 오브 레코드 — -CRM, ERP, 티켓팅 도구, 자체 제작 백오피스 — 는 이미 작동하고 있으며, -데이터가 이미 그곳에 있습니다. - -ObjectOS는 정반대의 입장을 취합니다. **마이그레이션하지 않습니다. -연결합니다.** - -## 한 문장으로 요약한 아이디어 - -ObjectOS를 기존 데이터베이스에 연결하고, 관심 있는 테이블을 객체로 -기술하면, 모든 AI 에이전트, 플로우, 대시보드가 즉시 그 데이터 위에서 -작동합니다 — 알맞은 시스템으로 자동 라우팅되고, 사용자가 이미 가진 동일한 -권한에 의해 통제됩니다. - -원본 애플리케이션은 변하지 않습니다. 행은 이동하지 않습니다. ObjectOS는 -여러분이 이미 운영 중인 시스템 위에 자리하는 AI 네이티브, 권한 인식 표면이 -됩니다. - -## 오늘날 작동하는 방식 - -네 단계가 있으며, 그 어느 것도 "앱을 재구축하라"가 아닙니다. - -1. **데이터베이스를 데이터소스로 연결합니다.** 데이터소스는 이름이 부여된 - 연결입니다 — Postgres, MySQL, MongoDB, SQLite. 자격 증명은 환경에서 - 가져오며, 먼저 분석만 하고 싶다면 연결을 읽기 전용으로 설정할 수 - 있습니다. - - ```ts - import type { Datasource } from '@objectstack/spec'; - - export const BusinessDb: Datasource = { - name: 'business_primary', - label: 'Business System (Postgres)', - driver: 'postgres', - config: { - connection: { - host: process.env.BIZ_DB_HOST, - user: process.env.BIZ_DB_USER, - password: process.env.BIZ_DB_PASSWORD, - database: process.env.BIZ_DB_NAME, - }, - }, - active: true, - }; - ``` - -2. **테이블을 객체로 모델링합니다** — 그리고 손으로 일일이 타이핑할 필요가 - 없습니다. Claude Code 같은 코딩 에이전트를 연결된 스키마에 연결하고 - 테이블당 소스 수준 객체 파일 하나를 생성하도록 요청하세요. 우리의 - [`hotcrm`](https://github.com/objectstack-ai/hotcrm) 레퍼런스 앱은 그 - 출력이 취하는 정확한 형태를 보여줍니다. 타입이 지정된 `Field.*` 정의와 - 외래 키를 위한 `Field.lookup(...)`을 갖춘 `ObjectSchema.create({ … })` - 입니다. 여러분은 검토하고 다듬습니다. 결과는 여러분의 것입니다. - -3. **객체를 데이터소스에 바인딩합니다** — 객체별로, 또는 네임스페이스 - 전체에 대한 라우팅 규칙으로: - - ```ts - datasourceMapping: [ - { namespace: 'biz', datasource: 'business_primary' }, - { default: true, datasource: 'default' }, - ] - ``` - -4. **AI가 작동하게 합니다.** 테이블이 객체가 되는 순간, AI 계층이 추가 - 작업 없이 그 위에서 작동합니다. 에이전트는 ObjectQL을 통해 조회하며, - ObjectQL은 각 객체를 해당 데이터베이스로 라우팅합니다 — 그리고 모든 - 쿼리는 **로그인한 사용자**로 실행되어, 객체 수준, 레코드 수준, 필드 수준 - 권한을 따릅니다. - -## 왜 이것이 안전한가 - -"우리 비즈니스 데이터 위의 AI"에 대한 반론은 언제나 거버넌스이며, 바로 +"비즈니스에 AI를 더하세요"라는 대부분의 제안은 은근히 재구축을 전제로 합니다. +데이터를 새 플랫폼으로 옮기고, 워크플로를 다시 구현하고, 팀을 재교육하고, +마이그레이션이 잘 끝나길 기도하는 것이죠. 아무도 원하지 않는 부분입니다. 기록 +시스템 —— CRM, ERP, 티켓팅 도구, 직접 만든 백오피스 —— 은 이미 잘 돌아가고 +있고, 데이터도 이미 거기에 있습니다. + +ObjectOS는 정반대의 입장을 취합니다. **마이그레이션하지 마세요. 연결하세요.** + +## 한 문장으로 + +ObjectOS를 기존 데이터베이스로 향하게 하고, 관심 있는 테이블을 객체로 +기술하면, 모든 AI 에이전트, 플로우, API, 대시보드가 즉시 그 데이터 위에서 +동작합니다 —— 올바른 시스템으로 자동 라우팅되고, 사용자가 이미 가진 동일한 +권한으로 통제됩니다. + +원래 애플리케이션은 바뀌지 않습니다. 행은 이동하지 않습니다. ObjectOS는 이미 +운영 중인 것 위에 얹히는, AI 네이티브하고 권한을 인식하는 표면이 됩니다. + +## 구체적인 그림 + +영업팀이 40개 테이블의 Postgres CRM 위에서 돌아간다고 합시다. 계정, 연락처, +기회(opportunity), 라인 아이템, 활동 —— 수년치의 실제 데이터이자, 담당자들이 +매일 쓰는 운영 앱입니다. 경영진이 원하는 건 두 가지입니다. 사람들이 그 데이터에 +자연어로 *질문할 수 있게* 하는 것("어떤 엔터프라이즈 거래가 Q2에서 밀려났고, +누가 담당인가?"), 그리고 자동화가 그 데이터를 안전하게 다루게 하는 것입니다. + +재구축의 답은 6개월짜리 프로젝트입니다. ObjectOS의 답은 한나절입니다. + +1. CRM 데이터베이스를 **읽기 전용** 데이터소스로 연결합니다. +2. 정말로 관심 있는 십여 개의 테이블을 코딩 에이전트가 객체로 모델링하게 합니다. +3. 데이터에 질문하고, 첫 자동화를 연결합니다. + +아무도 CRM을 건드리지 않습니다. 담당자들은 눈치채지도 못합니다. 그런데도 똑같은 +행 위에 AI 네이티브 레이어를 얻습니다. + +## 오늘 어떻게 동작하나 + +네 단계이며, 어느 것도 "앱을 다시 만드세요"가 아닙니다. + +### 1. 데이터베이스를 데이터소스로 연결하기 + +데이터소스는 이름이 붙은 연결입니다 —— Postgres, MySQL, MongoDB, SQLite. +자격 증명은 환경 변수에서 가져오며, 소스에 하드코딩하지 않습니다. 먼저 분석만 +하고 싶다면 읽기 복제본이나 읽기 전용 DB 사용자로 향하게 하세요. 그러면 쓰기는 +애초에 일어날 수 없습니다. + +```ts +import type { Datasource } from '@objectstack/spec'; + +export const BusinessDb: Datasource = { + name: 'business_primary', + label: 'Business System (Postgres)', + driver: 'postgres', + config: { + connection: { + host: process.env.BIZ_DB_HOST, + user: process.env.BIZ_DB_USER, + password: process.env.BIZ_DB_PASSWORD, + database: process.env.BIZ_DB_NAME, + }, + }, + pool: { min: 1, max: 10 }, + active: true, +}; +``` + +### 2. 테이블을 객체로 모델링하기 —— 코딩 에이전트로 + +이 단계는 느릴 거라 다들 예상하지만, 그렇지 않습니다. 테이블마다 객체를 손으로 +타이핑하지 않습니다. **Claude Code** 같은 코딩 에이전트를 연결된 스키마로 +향하게 하고, 인트로스펙션과 초안 작성을 맡깁니다. 다음처럼 평범한 프롬프트면 +충분합니다. + +> "`business_primary` 데이터소스에 연결해. 이 테이블들 —— `accounts`, +> `contacts`, `opportunities`, `line_items` —— 각각에 대해 +> `ObjectSchema.create`를 사용한 `src/objects/.object.ts` 파일을 하나씩 +> 생성해. SQL 컬럼을 알맞은 `Field.*` 타입에 매핑하고, 외래 키는 +> `Field.lookup(...)`으로 만들고, 각 객체에 `datasource: 'business_primary'`를 +> 설정해." + +에이전트는 실제 컬럼, 타입, 외래 키를 읽고 소스 수준의 객체 파일을 작성합니다. +우리의 [`hotcrm`](https://github.com/objectstack-ai/hotcrm) 레퍼런스 앱이 그 +출력의 정확한 형태를 보여줍니다. + +```ts +import { ObjectSchema, Field } from '@objectstack/spec/data'; + +export const Opportunity = ObjectSchema.create({ + name: 'biz_opportunity', + label: 'Opportunity', + datasource: 'business_primary', + fields: { + name: Field.text({ label: 'Name', required: true }), + account: Field.lookup({ label: 'Account', reference_to: 'biz_account' }), + amount: Field.currency({ label: 'Amount' }), + stage: Field.select({ label: 'Stage', options: [/* … */] }), + close_date: Field.date({ label: 'Close Date' }), + }, +}); +``` + +출력이 **여러분이 소유하고 커밋하는 평범한 소스**이기 때문에, 통제권은 늘 +여러분에게 있습니다. 중요한 컬럼은 남기고, 노출하고 싶지 않은 컬럼은 버리고, +그 위에 레이블, 검증, 권한을 얹으세요. 에이전트는 몇 분 만에 검토 가능한 +초안까지 데려다주고, 프로덕션 수준으로 다듬는 것은 여러분의 몫입니다. + +### 3. 객체를 데이터소스에 바인딩하기 + +각 객체는 `datasource`를 가집니다. 객체별로 설정하거나, 네임스페이스 전체에 대해 +라우팅 규칙을 한 번 선언하고 그 아래의 모든 객체가 상속하게 하세요. + +```ts +datasourceMapping: [ + { namespace: 'biz', datasource: 'business_primary' }, + { default: true, datasource: 'default' }, +] +``` + +규칙은 네임스페이스, 패키지, 객체 이름 glob으로 매칭되며, 첫 번째로 일치하는 +것이 적용됩니다. 데이터 레지던시 결정이 파일 곳곳에 흩어지지 않고 한곳에 +모입니다. + +### 4. AI에게 일을 맡기기 + +테이블이 객체가 되는 순간, AI 레이어가 그 위에서 공짜로 동작합니다. ObjectOS의 +에이전트와 도구 —— `list_objects`, `describe_object`, `query_records`, +`aggregate_data`, 그리고 data-chat 에이전트 —— 는 모두 **ObjectQL**을 거치며, +ObjectQL이 각 객체를 바인딩된 데이터소스로 라우팅하고, 드라이버가 지원하면 +필터·정렬·집계를 *데이터베이스로 푸시다운*합니다. + +그래서 사용자가 이렇게 물으면: + +> "어떤 엔터프라이즈 기회가 Q2에서 밀려났고, 누가 담당인가?" + +에이전트는 테이블 전체를 프롬프트에 쏟아붓지 않습니다. 이를 `biz_opportunity`에 +대한 ObjectQL 쿼리 —— 단계와 마감일에 대한 `WHERE`, 담당자에 대한 join —— 로 +컴파일하고, 여러분의 Postgres에서 `SELECT … WHERE …` 로 실행하여 실제의 최신 +행으로부터 답합니다. 그리고 결정적으로, 그 쿼리를 **로그인한 사용자**로 +실행합니다. 어떤 담당자가 CRM에서 다른 지역의 거래를 볼 수 없다면, 에이전트도 +볼 수 없습니다. + +## 왜 안전한가 + +"우리 비즈니스 데이터에 AI를 올린다"는 데 대한 반론은 늘 거버넌스이며, 바로 그곳에서 런타임이 일을 합니다. -- **AI는 사용자로서 작동하며, 결코 그들 위에 있지 않습니다.** 에이전트는 - 그 뒤의 사람이 볼 수 있도록 허용된 것만 정확히 봅니다 — 프롬프트가 아니라 - 런타임에서 강제됩니다. -- **원한다면 기본적으로 읽기 전용.** 객체를 읽기 전용 연결 또는 DB - 사용자에 바인딩하세요. 프로덕션을 안전하게 분석하고, 쓰기는 의도적으로 +- **AI는 사용자로서 행동하며, 결코 그 위에 있지 않습니다.** 에이전트는 그 + 뒤에 있는 사람이 볼 수 있도록 허용된 것만 정확히 봅니다 —— 객체·레코드·필드 + 수준 권한이 프롬프트가 아니라 런타임에서 강제됩니다. +- **원한다면 기본 읽기 전용.** 객체를 읽기 전용 연결이나 DB 사용자에 + 바인딩하세요. 프로덕션을 안전하게 분석하고, 쓰기는 의도적으로, 객체 단위로 활성화하세요. -- **모든 것이 감사됩니다.** 모든 읽기, 쓰기, 권한 상승 — 사람이든 - 에이전트든 — 은 누가, 무엇을, 언제, 왜 했는지와 함께 기록됩니다. +- **모든 것이 감사됩니다.** 모든 읽기, 쓰기, 권한 상승은 —— 사람이든 + 에이전트든 —— 누가, 무엇을, 언제, 왜로 기록됩니다. - **데이터는 여러분의 네트워크에 머뭅니다.** ObjectOS는 여러분의 환경에서 - 실행됩니다. 비즈니스 데이터와 프롬프트는 결코 여러분의 경계를 벗어나지 - 않습니다. + 실행됩니다. 비즈니스 데이터와 프롬프트는 결코 경계 밖으로 나가지 않습니다. -## 출시된 것 vs. 다가오는 것 +## 재구축 vs. 연결 -위의 흐름은 출시된 구성 요소들로 **오늘날** 작동합니다. 데이터소스, 객체별 -라우팅, 기능 인식 ObjectQL 푸시다운, 그리고 AI 에이전트 계층입니다. 객체 -생성은 연결된 스키마에 대해 코딩 에이전트로 수행됩니다 — `hotcrm` 객체가 -작성된 것과 동일한 방식입니다. +| | 새 플랫폼으로 재구축 | ObjectOS로 연결 | +|---|---|---| +| **첫 가치까지 걸리는 시간** | 수개월 | 한나절 | +| **기록 시스템에 대한 위험** | 높음 —— 데이터 마이그레이션, 이중 쓰기, 전환 | 없음 —— 원본 앱은 그대로 | +| **데이터가 있는 곳** | 이동됨 | 있던 그 자리에 그대로 | +| **모델링 노력** | 모든 엔터티를 손으로 재구현 | 에이전트가 라이브 스키마에서 객체 초안 작성 | +| **권한** | 재구축·재감사 | 상속됨; AI는 동일한 모델을 따름 | +| **되돌리기** | 되돌리기 어려움 | 데이터소스 연결 해제 —— 아무것도 바뀌지 않음 | -더 풍부한 **턴키 페더레이션** 경험 — 원스텝 스키마 가져오기, 외부 소유 -스키마에 대한 바인딩, 내장 쓰기 안전 게이트 — 는 +## 첫날 얻는 것 + +몇 개의 테이블이 모델링되고 바인딩되면: + +- **자연어 분석**이 라이브 레코드에 대해 ObjectQL을 통해 계산됩니다 —— 오래된 + 내보내기가 아니라. +- **통제된 자동화.** 플로우와 액션이 같은 데이터를 읽고 (허용된 곳에서) 쓰며, + 모든 단계가 감사됩니다. +- **생성된 API와 콘솔.** REST/GraphQL 엔드포인트와 관리 화면이 동일한 + 메타데이터에서 나옵니다 —— 별도의 통합 계층이 필요 없습니다. +- **하나의 권한 모델.** 사람에게 적용되는 경계가 AI 트래픽에도 동일하게 + 적용됩니다. + +## 출시된 것 vs. 준비 중인 것 + +위 흐름은 출시된 빌딩 블록 —— 데이터소스, 객체별 라우팅, 능력 인식 ObjectQL +푸시다운, AI 에이전트 레이어 —— 로 **오늘** 동작합니다. 객체 모델링은 연결된 +스키마에 대해 코딩 에이전트로 수행됩니다 —— `hotcrm`의 객체가 작성된 것과 같은 +방식입니다. + +더 풍부한 **턴키 페더레이션** 경험 —— 한 단계 스키마 가져오기, 외부 소유 스키마 +바인딩, 내장된 쓰기 안전 게이트 —— 는 [ADR-0015](https://github.com/objectstack-ai/framework/blob/main/docs/adr/0015-external-datasource-federation.md) -아래에서 활발히 설계 중입니다(상태: *Proposed*). 그것이 도착하면 더 많이 -쓰겠습니다. 그때까지는, 문서화된 경로가 지원되는 경로입니다. +(상태: *Proposed*) 아래에서 활발히 설계 중입니다. 출시되는 대로 더 쓰겠습니다. +그때까지는 문서화된 경로 —— 연결, 모델링, 바인딩, 쿼리 —— 가 지원되는 길입니다. + +## 자주 묻는 질문 + +**모든 테이블을 모델링해야 하나요?** 아니요. AI와 자동화가 다루길 원하는 +테이블만 모델링하세요. 데이터베이스의 나머지는 무시됩니다. + +**이게 내 프로덕션 데이터베이스에 쓰나요?** 여러분이 허용할 때만요. 읽기 전용 +연결이나 DB 사용자에 바인딩하면 쓰기는 불가능하며, 준비되면 객체 단위로 +의도적으로 활성화하세요. + +**내 데이터가 모델 제공자에게 가나요?** ObjectOS는 여러분의 환경에서 실행되고, +쿼리는 여러분의 데이터베이스에 대해 실행됩니다. 어떤 AI 제공자를 구성하고 무엇을 +보게 할지는 여러분이 통제합니다. + +**스키마가 바뀌면요?** 업데이트된 스키마에 대해 코딩 에이전트를 다시 실행해 +영향받은 객체를 재생성하거나 diff하세요 —— 그것들은 그저 저장소 안의 소스 +파일입니다. -## 사용해보기 +## 시작해 보기 -- [데이터 소스](/docs/configure/data-sources) — 전체 작성 가이드 -- [기존 시스템 확장](/docs/extend-existing-systems) — 시나리오, 처음부터 끝까지 -- [AI 에이전트](/docs/build/agents) — 여러분의 객체 위의 선언적 에이전트 +- [데이터소스](/docs/configure/data-sources) —— 전체 작성 가이드 +- [기존 시스템 확장](/docs/extend-existing-systems) —— 처음부터 끝까지의 시나리오 +- [AI 에이전트](/docs/build/agents) —— 객체 위의 선언적 에이전트 -이미 비즈니스 데이터베이스가 있다면, 여러분은 이미 거의 다 온 것입니다. -그것을 연결하고, 몇 개의 테이블을 모델링한 다음, 데이터에게 질문을 던지세요. +이미 비즈니스 데이터베이스가 있다면, 이미 거의 다 온 셈입니다. 연결하고, 몇 개의 +테이블을 모델링하고, 데이터에 질문을 던져 보세요. diff --git a/content/blog/extend-existing-systems-with-ai.mdx b/content/blog/extend-existing-systems-with-ai.mdx index 315590e..34f4dae 100644 --- a/content/blog/extend-existing-systems-with-ai.mdx +++ b/content/blog/extend-existing-systems-with-ai.mdx @@ -1,6 +1,6 @@ --- title: Make Your Existing Business System AI-Native — Without a Migration -description: Connect ObjectOS to the database you already run, model the tables as objects, and let AI query and act on real data — under your permissions, on your servers. +description: Connect ObjectOS to the database you already run, let a coding agent model the tables as objects, and put AI on real data — under your permissions, on your servers, with the original system untouched. author: ObjectStack Team date: 2026-05-30 tags: @@ -10,74 +10,149 @@ tags: --- Most "add AI to your business" pitches quietly assume a rebuild: lift the -data into a new platform, re-implement the workflows, re-train the team. -That's the part nobody wants. The system of record — the CRM, the ERP, -the ticketing tool, the homegrown back office — already works, and it's -already where the data lives. +data into a new platform, re-implement the workflows, re-train the team, +and pray the migration lands. That's the part nobody wants. The system of +record — the CRM, the ERP, the ticketing tool, the homegrown back office — +already works, and it's already where the data lives. ObjectOS takes the opposite stance. **You don't migrate. You connect.** ## The idea in one sentence Point ObjectOS at your existing database, describe the tables you care -about as objects, and every AI agent, flow, and dashboard immediately -works on that data — routed automatically to the right system, governed -by the same permissions your users already have. +about as objects, and every AI agent, flow, API, and dashboard immediately +works on that data — routed automatically to the right system, governed by +the same permissions your users already have. The original application doesn't change. The rows don't move. ObjectOS -becomes the AI-native, permission-aware surface on top of what you -already run. +becomes the AI-native, permission-aware surface on top of what you already +run. + +## A concrete picture + +Say you run a sales team on a 40-table Postgres CRM. Accounts, contacts, +opportunities, line items, activities — years of real data, a production +app your reps use every day. Leadership wants two things: let people *ask +questions* of that data in plain language ("which enterprise deals slipped +out of Q2, and who owns them?"), and let automations act on it safely. + +The rebuild answer is a six-month project. The ObjectOS answer is an +afternoon: + +1. Connect the CRM database as a **read-only** datasource. +2. Have a coding agent model the dozen tables you actually care about as + objects. +3. Ask your data questions, and wire up the first automation. + +Nobody touches the CRM. The reps never notice. You get an AI-native layer +on top of the exact same rows. ## How it works today -There are four steps, and none of them is "rebuild your app": - -1. **Connect the database as a datasource.** A datasource is a named - connection — Postgres, MySQL, MongoDB, SQLite. Credentials come from - the environment, and the connection can be read-only if you only want - to analyze first. - - ```ts - import type { Datasource } from '@objectstack/spec'; - - export const BusinessDb: Datasource = { - name: 'business_primary', - label: 'Business System (Postgres)', - driver: 'postgres', - config: { - connection: { - host: process.env.BIZ_DB_HOST, - user: process.env.BIZ_DB_USER, - password: process.env.BIZ_DB_PASSWORD, - database: process.env.BIZ_DB_NAME, - }, - }, - active: true, - }; - ``` - -2. **Model the tables as objects** — and you don't have to type them by - hand. Point a coding agent like Claude Code at the connected schema and - ask it to generate one source-level object file per table. Our - [`hotcrm`](https://github.com/objectstack-ai/hotcrm) reference app - shows the exact shape that output takes: an `ObjectSchema.create({ … })` - with typed `Field.*` definitions and `Field.lookup(...)` for foreign - keys. You review and refine; you own the result. - -3. **Bind objects to the datasource** — per object, or with a routing - rule for a whole namespace: - - ```ts - datasourceMapping: [ - { namespace: 'biz', datasource: 'business_primary' }, - { default: true, datasource: 'default' }, - ] - ``` - -4. **Let AI work.** The moment a table is an object, the AI layer works - on it for free. Agents query through ObjectQL, which routes each object - to its database — and every query runs as the **signed-in user**, - obeying object-, record-, and field-level permissions. +There are four steps, and none of them is "rebuild your app." + +### 1. Connect the database as a datasource + +A datasource is a named connection — Postgres, MySQL, MongoDB, SQLite. +Credentials come from the environment, never inlined in source. If you only +want to analyze first, point it at a read replica or a read-only DB user +and writes simply can't happen. + +```ts +import type { Datasource } from '@objectstack/spec'; + +export const BusinessDb: Datasource = { + name: 'business_primary', + label: 'Business System (Postgres)', + driver: 'postgres', + config: { + connection: { + host: process.env.BIZ_DB_HOST, + user: process.env.BIZ_DB_USER, + password: process.env.BIZ_DB_PASSWORD, + database: process.env.BIZ_DB_NAME, + }, + }, + pool: { min: 1, max: 10 }, + active: true, +}; +``` + +### 2. Model the tables as objects — with a coding agent + +This is the step people expect to be slow, and it isn't. You don't +hand-type an object per table. You point a coding agent like **Claude +Code** at the connected schema and let it do the introspection and the +first draft. A prompt as plain as: + +> "Connect to the `business_primary` datasource. For each of these tables — +> `accounts`, `contacts`, `opportunities`, `line_items` — generate one +> `src/objects/.object.ts` file using `ObjectSchema.create`. Map SQL +> columns to the right `Field.*` types, turn foreign keys into +> `Field.lookup(...)`, and set `datasource: 'business_primary'` on each." + +The agent reads the real columns, types, and foreign keys and writes +source-level object files. Our +[`hotcrm`](https://github.com/objectstack-ai/hotcrm) reference app shows +the exact shape that output takes: + +```ts +import { ObjectSchema, Field } from '@objectstack/spec/data'; + +export const Opportunity = ObjectSchema.create({ + name: 'biz_opportunity', + label: 'Opportunity', + datasource: 'business_primary', + fields: { + name: Field.text({ label: 'Name', required: true }), + account: Field.lookup({ label: 'Account', reference_to: 'biz_account' }), + amount: Field.currency({ label: 'Amount' }), + stage: Field.select({ label: 'Stage', options: [/* … */] }), + close_date: Field.date({ label: 'Close Date' }), + }, +}); +``` + +Because the output is **ordinary source you own and commit**, you stay in +control: keep the columns that matter, drop the ones you don't want +exposed, and layer on labels, validations, and permissions. The agent gets +you to a reviewable draft in minutes; you make it production-grade. + +### 3. Bind objects to the datasource + +Each object carries a `datasource`. Set it per object, or declare a routing +rule once for a whole namespace and let every object under it inherit: + +```ts +datasourceMapping: [ + { namespace: 'biz', datasource: 'business_primary' }, + { default: true, datasource: 'default' }, +] +``` + +Rules match by namespace, package, or object-name glob; first match wins. +Data-residency decisions live in one place instead of scattered across +files. + +### 4. Let AI work + +The moment a table is an object, the AI layer works on it for free. +ObjectOS's agents and tools — `list_objects`, `describe_object`, +`query_records`, `aggregate_data`, and the data-chat agent — all go through +**ObjectQL**, which routes each object to its bound datasource and pushes +filters, sorts, and aggregations *down into the database* when the driver +supports them. + +So when a user asks: + +> "Which enterprise opportunities slipped out of Q2, and who owns them?" + +the agent doesn't slurp the whole table into a prompt. It compiles that +into an ObjectQL query against `biz_opportunity` — a `WHERE` on stage and +close-date, a join to the owner — runs it as `SELECT … WHERE …` on your +Postgres, and answers from the real, current rows. And critically, it runs +that query **as the signed-in user**: if a rep can't see another region's +deals in the CRM, the agent can't either. ## Why this is safe @@ -85,21 +160,45 @@ The objection to "AI on our business data" is always governance, and that's exactly where the runtime does the work: - **AI acts as the user, never above them.** An agent sees precisely what - the person behind it is allowed to see — enforced in the runtime, not - the prompt. + the person behind it is allowed to see — object-, record-, and + field-level permissions enforced in the runtime, not in the prompt. - **Read-only by default if you want it.** Bind objects to a read-only connection or DB user. Analyze production safely; enable writes - deliberately. + deliberately, one object at a time. - **Everything audited.** Every read, write, and escalation — human or agent — is recorded with who, what, when, and why. - **Your data stays in your network.** ObjectOS runs in your environment. Business data and prompts never leave your perimeter. +## Rebuild vs. connect + +| | Rebuild onto a new platform | Connect with ObjectOS | +|---|---|---| +| **Time to first value** | Months | An afternoon | +| **Risk to the system of record** | High — data migration, dual-writes, cutover | None — the source app is untouched | +| **Where the data lives** | Moved | Stays exactly where it is | +| **Modeling effort** | Re-implement every entity by hand | Coding agent drafts objects from the live schema | +| **Permissions** | Re-built and re-audited | Inherited; AI obeys the same model | +| **Reversibility** | Hard to undo | Disconnect the datasource — nothing changed | + +## What you get on day one + +Once a handful of tables are modeled and bound: + +- **Natural-language analysis** over live records, computed through + ObjectQL — not a stale export. +- **Governed automation.** Flows and actions read and (where allowed) write + the same data, every step audited. +- **A generated API and Console.** REST/GraphQL endpoints and admin screens + come from the same metadata — no extra integration layer to build. +- **One permission model.** The boundary that applies to humans applies + identically to AI traffic. + ## What's shipped vs. what's coming The flow above works **today** with shipped building blocks: datasources, per-object routing, capability-aware ObjectQL pushdown, and the AI agent -layer. The object generation is done with a coding agent against your +layer. The object modeling is done with a coding agent against your connected schema — the same way the `hotcrm` objects were authored. A richer, **turn-key federation** experience — one-step schema import, @@ -107,7 +206,24 @@ binding to externally owned schemas, and built-in write-safety gates — is in active design under [ADR-0015](https://github.com/objectstack-ai/framework/blob/main/docs/adr/0015-external-datasource-federation.md) (status: *Proposed*). We'll write more as it lands. Until then, the -documented path is the supported one. +documented path — connect, model, bind, query — is the supported one. + +## Frequently asked + +**Do I have to model every table?** No. Model only the tables you want AI +and automation to touch. The rest of the database is ignored. + +**Will this write to my production database?** Only if you let it. Bind to a +read-only connection or DB user and writes are impossible; enable them +deliberately, per object, when you're ready. + +**Does my data go to a model provider?** ObjectOS runs in your environment, +and queries run against your database. You control which AI provider is +configured and what it's allowed to see. + +**What if my schema changes?** Re-run the coding agent against the updated +schema to regenerate or diff the affected objects — they're just source +files in your repo. ## Try it diff --git a/content/blog/extend-existing-systems-with-ai.zh-Hans.mdx b/content/blog/extend-existing-systems-with-ai.zh-Hans.mdx index 396d67c..ffea803 100644 --- a/content/blog/extend-existing-systems-with-ai.zh-Hans.mdx +++ b/content/blog/extend-existing-systems-with-ai.zh-Hans.mdx @@ -1,6 +1,6 @@ --- title: 让你现有的业务系统原生支持 AI —— 无需迁移 -description: 把 ObjectOS 连到你已经在运行的数据库，将数据表建模为对象，让 AI 查询并操作真实数据 —— 在你的权限之下，在你的服务器之上。 +description: 把 ObjectOS 连到你已经在运行的数据库，让编码 Agent 把数据表建模为对象，再为真实数据叠加 AI —— 在你的权限之下、在你的服务器之上，原系统毫发无损。 author: ObjectStack Team date: 2026-05-30 tags: @@ -9,92 +9,198 @@ tags: - Architecture --- -大多数"给你的业务加上 AI"的说辞，都悄悄假设了一次重建：把数据搬到一个新平台， -重新实现工作流，重新培训团队。而这正是没人想做的部分。那套记录系统 —— -CRM、ERP、工单工具、自研的后办公系统 —— 已经在运转，数据也已经在那里。 +大多数"给你的业务加上 AI"的说辞，都悄悄假设了一次重建：把数据搬到新平台、 +重新实现工作流、重新培训团队，然后祈祷迁移顺利落地。而这正是没人想做的部分。 +那套记录系统 —— CRM、ERP、工单工具、自研的后办公系统 —— 已经在运转，数据 +也已经在那里。 ObjectOS 采取相反的立场。**你不迁移。你连接。** ## 一句话讲清这个想法 把 ObjectOS 指向你现有的数据库，将你关心的数据表描述为对象，于是每一个 AI -Agent、流程和仪表盘都立刻在这些数据上工作 —— 自动路由到正确的系统，并受你的 -用户已经拥有的同一套权限治理。 +Agent、流程、API 和仪表盘都立刻在这些数据上工作 —— 自动路由到正确的系统， +并受你的用户已经拥有的同一套权限治理。 -原有的应用不会改变。数据行不会移动。ObjectOS 成为你已运行系统之上那层原生支持 -AI、感知权限的界面。 +原有的应用不会改变。数据行不会移动。ObjectOS 成为你已运行系统之上那层原生 +支持 AI、感知权限的界面。 + +## 一个具体的画面 + +假设你的销售团队跑在一个 40 张表的 Postgres CRM 上。客户、联系人、商机、 +明细行、活动 —— 多年的真实数据，一个销售每天都在用的生产应用。管理层想要 +两件事：让大家用自然语言*向数据提问*（"哪些企业级商机滑出了 Q2，分别是谁 +在负责？"），以及让自动化安全地操作这些数据。 + +重建的答案是一个六个月的项目。ObjectOS 的答案是一个下午： + +1. 把 CRM 数据库连接为一个**只读**数据源。 +2. 让编码 Agent 把你真正关心的那十来张表建模为对象。 +3. 向你的数据提问，并接上第一条自动化。 + +没人碰 CRM。销售毫无察觉。而你在完全相同的数据行之上，得到了一层原生支持 +AI 的能力。 ## 它今天如何运作 -一共四步，而且没有一步是"重建你的应用"： - -1. **将数据库连接为数据源（datasource）。** 数据源是一个具名连接 —— - Postgres、MySQL、MongoDB、SQLite。凭据来自环境变量，如果你想先做分析， - 这个连接也可以是只读的。 - - ```ts - import type { Datasource } from '@objectstack/spec'; - - export const BusinessDb: Datasource = { - name: 'business_primary', - label: 'Business System (Postgres)', - driver: 'postgres', - config: { - connection: { - host: process.env.BIZ_DB_HOST, - user: process.env.BIZ_DB_USER, - password: process.env.BIZ_DB_PASSWORD, - database: process.env.BIZ_DB_NAME, - }, - }, - active: true, - }; - ``` - -2. **将数据表建模为对象** —— 而且你不必手工敲出它们。把像 Claude Code 这样的 - 编码 Agent 指向已连接的 schema，让它为每张表生成一个源级别的对象文件。我们的 - [`hotcrm`](https://github.com/objectstack-ai/hotcrm) 参考应用展示了输出的确切 - 形态：一个 `ObjectSchema.create({ … })`，带有类型化的 `Field.*` 定义，外键则用 - `Field.lookup(...)`。你来审阅和打磨；结果归你所有。 - -3. **将对象绑定到数据源** —— 可以逐个对象绑定，也可以用一条路由规则绑定整个 - 命名空间： - - ```ts - datasourceMapping: [ - { namespace: 'biz', datasource: 'business_primary' }, - { default: true, datasource: 'default' }, - ] - ``` - -4. **让 AI 开始工作。** 一旦一张表成为对象，AI 层就能免费地在它上面工作。Agent - 通过 ObjectQL 查询，由它将每个对象路由到对应的数据库 —— 而且每一次查询都以 - **已登录用户**的身份运行，遵守对象级、记录级和字段级的权限。 +一共四步，而且没有一步是"重建你的应用"。 + +### 1. 将数据库连接为数据源 + +数据源是一个具名连接 —— Postgres、MySQL、MongoDB、SQLite。凭据来自环境 +变量，绝不写死在源码里。如果你想先做分析，把它指向只读副本或只读数据库 +用户，写入便根本无从发生。 + +```ts +import type { Datasource } from '@objectstack/spec'; + +export const BusinessDb: Datasource = { + name: 'business_primary', + label: 'Business System (Postgres)', + driver: 'postgres', + config: { + connection: { + host: process.env.BIZ_DB_HOST, + user: process.env.BIZ_DB_USER, + password: process.env.BIZ_DB_PASSWORD, + database: process.env.BIZ_DB_NAME, + }, + }, + pool: { min: 1, max: 10 }, + active: true, +}; +``` + +### 2. 将数据表建模为对象 —— 交给编码 Agent + +这一步人们以为会很慢，其实不然。你不必为每张表手工敲对象。把像 **Claude +Code** 这样的编码 Agent 指向已连接的 schema，让它完成内省与初稿。一句朴素 +的提示就够了： + +> "连接到 `business_primary` 数据源。为这几张表 —— `accounts`、`contacts`、 +> `opportunities`、`line_items` —— 各生成一个 `src/objects/.object.ts` +> 文件，使用 `ObjectSchema.create`。把 SQL 列映射到合适的 `Field.*` 类型， +> 把外键转成 `Field.lookup(...)`，并在每个对象上设置 +> `datasource: 'business_primary'`。" + +Agent 会读取真实的列、类型和外键，写出源级别的对象文件。我们的 +[`hotcrm`](https://github.com/objectstack-ai/hotcrm) 参考应用展示了输出的 +确切形态： + +```ts +import { ObjectSchema, Field } from '@objectstack/spec/data'; + +export const Opportunity = ObjectSchema.create({ + name: 'biz_opportunity', + label: 'Opportunity', + datasource: 'business_primary', + fields: { + name: Field.text({ label: 'Name', required: true }), + account: Field.lookup({ label: 'Account', reference_to: 'biz_account' }), + amount: Field.currency({ label: 'Amount' }), + stage: Field.select({ label: 'Stage', options: [/* … */] }), + close_date: Field.date({ label: 'Close Date' }), + }, +}); +``` + +因为产物是**你拥有并提交的普通源码**，你始终掌握控制权：保留重要的列、丢弃 +不想暴露的列，再叠加 label、校验与权限。Agent 几分钟内把你带到一份可审阅的 +初稿；你来让它达到生产级别。 + +### 3. 将对象绑定到数据源 + +每个对象都带有 `datasource`。可以逐个对象设置，也可以为整个命名空间声明一条 +路由规则，让其下每个对象继承： + +```ts +datasourceMapping: [ + { namespace: 'biz', datasource: 'business_primary' }, + { default: true, datasource: 'default' }, +] +``` + +规则按命名空间、包名或对象名 glob 匹配；首个命中者生效。数据驻留的决策集中 +在一处，而不是散落在各个文件里。 + +### 4. 让 AI 开始工作 + +一旦一张表成为对象，AI 层就能免费地在它上面工作。ObjectOS 的 Agent 与工具 —— +`list_objects`、`describe_object`、`query_records`、`aggregate_data` 以及 +data-chat agent —— 都经由 **ObjectQL**，由它将每个对象路由到所绑定的数据源， +并在驱动支持时把过滤、排序与聚合*下推进数据库*。 + +于是当用户问： + +> "哪些企业级商机滑出了 Q2，分别是谁在负责？" + +Agent 不会把整张表灌进提示词。它会把这句话编译成一条针对 `biz_opportunity` +的 ObjectQL 查询 —— 对阶段和关闭日期的 `WHERE`、对负责人的 join —— 在你的 +Postgres 上以 `SELECT … WHERE …` 执行，并基于真实、当前的数据行作答。而且 +关键在于，它以**已登录用户**的身份运行这条查询：如果某个销售在 CRM 里看不到 +其他区域的商机，Agent 也同样看不到。 ## 为什么这是安全的 -对"在我们的业务数据上跑 AI"的质疑总是关于治理，而这恰恰是运行时发挥作用的地方： +对"在我们的业务数据上跑 AI"的质疑总是关于治理，而这恰恰是运行时发挥作用的 +地方： -- **AI 以用户身份行动，绝不凌驾其上。** Agent 看到的，恰好是它背后那个人被允许 - 看到的内容 —— 由运行时强制，而非由提示词约束。 -- **如果你愿意，默认只读。** 把对象绑定到一个只读连接或只读数据库用户。安全地 - 分析生产数据；再有意识地开启写入。 +- **AI 以用户身份行动，绝不凌驾其上。** Agent 看到的，恰好是它背后那个人被 + 允许看到的内容 —— 对象级、记录级、字段级权限由运行时强制，而非由提示词约束。 +- **如果你愿意，默认只读。** 把对象绑定到只读连接或只读数据库用户。安全地 + 分析生产数据；再有意识地、一个对象一个对象地开启写入。 - **一切皆有审计。** 每一次读取、写入和提权 —— 无论来自人还是 Agent —— 都记录下何人、何事、何时、何因。 -- **你的数据留在你的网络里。** ObjectOS 跑在你的环境中。业务数据和提示词从不 - 离开你的边界。 +- **你的数据留在你的网络里。** ObjectOS 跑在你的环境中。业务数据和提示词 + 从不离开你的边界。 + +## 重建 vs. 连接 + +| | 重建到新平台 | 用 ObjectOS 连接 | +|---|---|---| +| **首次见效时间** | 数月 | 一个下午 | +| **对记录系统的风险** | 高 —— 数据迁移、双写、切换上线 | 无 —— 源应用毫发无损 | +| **数据存放在哪** | 被搬走 | 原地不动 | +| **建模工作量** | 手工重新实现每个实体 | 编码 Agent 从真实 schema 起草对象 | +| **权限** | 重建并重新审计 | 继承；AI 遵守同一套模型 | +| **可逆性** | 难以撤销 | 断开数据源 —— 什么都没变 | + +## 第一天你就能得到什么 + +一旦几张表被建模并绑定： + +- **自然语言分析**作用于实时记录，经由 ObjectQL 计算 —— 而非一份过期的导出。 +- **受治理的自动化。** 流程与动作读取、并（在允许处）写入同一批数据，每一步 + 皆有审计。 +- **生成式 API 与控制台。** REST/GraphQL 端点与管理界面源自同一份元数据 —— + 无需另建集成层。 +- **同一套权限模型。** 适用于人的边界，同样适用于 AI 流量。 ## 已经交付的 vs. 即将到来的 上面这套流程**今天**就能用，凭借的是已交付的构建块：数据源、按对象路由、 -感知能力的 ObjectQL 下推（pushdown），以及 AI Agent 层。对象的生成由一个编码 -Agent 针对你已连接的 schema 完成 —— 与 `hotcrm` 的对象被编写出来的方式相同。 +感知能力的 ObjectQL 下推，以及 AI Agent 层。对象的建模由一个编码 Agent 针对 +你已连接的 schema 完成 —— 与 `hotcrm` 的对象被编写出来的方式相同。 -一套更丰富的**开箱即用联邦（turn-key federation）**体验 —— 一步式 schema 导入、 -绑定到外部拥有的 schema、内建的写入安全闸门 —— 正在 +一套更丰富的**开箱即用联邦（turn-key federation）**体验 —— 一步式 schema +导入、绑定到外部拥有的 schema、内建的写入安全闸门 —— 正在 [ADR-0015](https://github.com/objectstack-ai/framework/blob/main/docs/adr/0015-external-datasource-federation.md) 下积极设计（状态：*Proposed*）。随着它落地，我们会写更多内容。在那之前， -有文档记载的路径才是受支持的路径。 +有文档记载的路径 —— 连接、建模、绑定、查询 —— 才是受支持的路径。 + +## 常见问题 + +**我必须把每张表都建模吗？** 不必。只建模你想让 AI 和自动化触及的表。数据库 +其余部分会被忽略。 + +**这会写入我的生产数据库吗？** 只有你允许才会。绑定到只读连接或只读数据库 +用户，写入便不可能发生；准备好后，再有意识地、按对象开启写入。 + +**我的数据会发给模型厂商吗？** ObjectOS 跑在你的环境中，查询在你的数据库上 +执行。配置哪个 AI 提供方、允许它看到什么，由你掌控。 + +**如果我的 schema 变了怎么办？** 针对更新后的 schema 重新运行编码 Agent， +重新生成或对受影响的对象做 diff —— 它们不过是你仓库里的源码文件。 ## 试一试