diff --git a/content/docs/architecture.mdx b/content/docs/architecture.mdx index 8837f8c..bb11c6c 100644 --- a/content/docs/architecture.mdx +++ b/content/docs/architecture.mdx @@ -8,15 +8,38 @@ A practical view of what runs when you deploy ObjectOS — on your own machines with **ObjectOS Enterprise**, or operated for you on **ObjectOS Cloud** — what data leaves your network, and what doesn't. -The mental model is two thin layers: - -1. **Metadata** — packages of objects / views / actions / flows / - agents. Mostly written by the [AI Builder](/docs/build/ai-builder) - against a sandboxed tool API; sometimes hand-edited, always +The mental model is one definition and one runtime that runs it: + +1. **Your [ontology](/docs/ontology)** — the definition of the business: + objects and fields, relations, actions, permissions, flows, and agent + and tool definitions. Views, dashboards, apps and translations are + authored beside it as its projections. Mostly written by the + [AI Builder](/docs/build/ai-builder) against a sandboxed tool API; + sometimes hand-edited; always validated before it runs, version-controlled and audited. -2. **A single Node.js runtime** that interprets that metadata into a - working application — REST API, Console UI, permissions, jobs, AI - tools — all in one process, talking to your database. +2. **A single Node.js runtime** that **derives** the working application + from it — the database schema, the REST API, the Console UI and the MCP + server agents call — and **enforces** it on every call: RBAC, + row-level and field-level security, sharing and audit apply to a REST + request, a Console click and an agent's tool call alike. All in one + process, talking to your database. + +```text +your ontology + objects · relations · actions + permissions · flows · agents + + projections: views · dashboards + apps · translations + │ + ▼ +ObjectOS runtime + derives the app, enforces it + │ + ├──▶ database its schema + ├──▶ REST API /api/v1/* + ├──▶ Console /_console/ + └──▶ MCP server /api/v1/mcp +``` No code generation step, no deploy pipeline between "user described what they want" and "it's live". The runtime hot-loads the new @@ -39,6 +62,7 @@ licensed runtime image described under [Deployment](/docs/deploy). │ │ ├─ Security (RBAC + row-level + field) │ │ │ │ ├─ ObjectQL (data engine, generates SQL) │ │ │ │ ├─ REST API generator │ │ +│ │ ├─ MCP server (/api/v1/mcp, on by default) │ │ │ │ └─ Capabilities loaded per artifact │ │ │ │ (audit, storage, jobs, queue, AI …) │ │ │ └───────────────────────────────────────────────┘ │ @@ -81,11 +105,17 @@ supported license and cloud-posture pairs. 2. HTTP dispatcher (security headers, request id) 3. AuthPlugin — session cookie, bearer token, or API key 4. SecurityPlugin — RBAC + row-level + field-level checks -5. Route handler — generated REST, declarative action, or custom +5. Route handler — generated REST, MCP tool call, declarative action, + or custom 6. Data driver — ObjectQL compiles to SQL / Mongo query 7. Response with X-Request-Id propagated ``` +An agent's call takes the same path. An MCP client authenticates as a +user, by OAuth or an API key, and the same permission checks bound what +its tool calls read and write — see +[Connect AI Tools (MCP)](/docs/configure/mcp). + The app is already resolved before the first request arrives: the kernel is built during startup, and the process does not report itself [ready](/docs/deploy/docker) until it is. So a served request carries no diff --git a/content/docs/build/agents.mdx b/content/docs/build/agents.mdx index 7dbb210..8682cc6 100644 --- a/content/docs/build/agents.mdx +++ b/content/docs/build/agents.mdx @@ -75,7 +75,7 @@ export const ticketManagement = defineSkill({ 'update_ticket', 'close_ticket', 'escalate_ticket', - 'action_*', // wildcard: pick up any future actions on the active object + 'action_*', // wildcard: every action the app exposes to AI (`ai.exposed`) ], }); ``` @@ -85,19 +85,26 @@ agents. ## Tools come from your declared metadata -Every `*.action.ts` you declare automatically materializes as an -`action_` tool — no separate wiring. So if you've already -defined `escalate_ticket` as an Action on the `support_ticket` object, -both the AI Builder and your Agents can call it. Permissions still -apply: the agent calls the action **as the user**, so the user's -permission set decides whether it succeeds. +An action becomes an `action_` tool **when its author exposes it +to AI** — `ai: { exposed: true }` with an `ai.description` of at least 40 +characters — and its type runs without a UI (`script`, `flow` or `api`). +Nothing else needs wiring: if `escalate_ticket` on the `support_ticket` +object is exposed, both the AI Builder and your Agents can call it. An +action left unexposed is invisible to agents and refused if called, +whatever capabilities the caller holds. + +The call is checked **as the user**: the action's `requiredPermissions` +decide whether it may fire, and it loads the record as that user. A +`script` body then runs as trusted app code, so expose an action only +when its body is safe to run for anyone those checks let through. See +[Actions](/docs/build/interface/actions#permissions). You can also expose: | Tool type | Source | |---|---| -| **Action** | Any `*.action.ts` in any installed package | -| **Flow** | A `type: 'flow'` action — the agent calls the action, which starts the flow | +| **Action** | Any action exposed to AI (`ai.exposed`), in any installed package | +| **Flow** | An exposed `type: 'flow'` action — the agent calls the action, which starts the flow | | **Query** | Saved ObjectQL queries (`*.query.ts`) | | **Knowledge search** | The `search_knowledge` tool, over the sources the user may read | | **MCP method** | Anything exposed by an attached MCP server | diff --git a/content/docs/build/ai-builder.mdx b/content/docs/build/ai-builder.mdx index dcf08ac..1c99662 100644 --- a/content/docs/build/ai-builder.mdx +++ b/content/docs/build/ai-builder.mdx @@ -56,11 +56,14 @@ namespaced and validated against `@objectstack/spec`: | | `modify_field` | Change label, picklist options, validation | | | `delete_field` | Remove a field (with safety check) | | **Data** | `query_data` | Read records via ObjectQL | -| **Actions / Knowledge** | `action_`, `search_knowledge` | Invoke actions, RAG over docs | - -Plus action tools materialized from every declared `*.action.ts` — -named `action_` — so once an action exists in the package, -the AI can call it like any built-in tool. +| **Actions / Knowledge** | `action_`, `search_knowledge` | Invoke the actions exposed to AI, RAG over docs | + +Plus one `action_` tool for each action its author **exposed to +AI** — `ai: { exposed: true }` with an `ai.description` of at least 40 +characters, on a type that runs without a UI (`script`, `flow` or `api`). +Once an action is exposed, the AI can call it like any built-in tool; an +action that is not exposed never becomes one. See +[Actions](/docs/build/interface/actions#from-an-ai-agent). See the full tool catalog at runtime: `GET /api/v1/ai/tools`. diff --git a/content/docs/build/index.de.mdx b/content/docs/build/index.de.mdx deleted file mode 100644 index aa2af5a..0000000 --- a/content/docs/build/index.de.mdx +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Erstellen -description: Wie Apps in ObjectOS zum Leben erwachen — durch Chatten mit der KI, durch Klicken in der Console oder durch das Forken einer Vorlage. -translation: - source_sha: 59546f7a9524eea345e390f398a98223cc6d8f109070ac21cec910a2935bdf52 - guide_rev: 1 - mode: auto ---- - -In ObjectOS schreibt der Kunde keine Metadaten. **Er beschreibt, was -er möchte, und die KI erstellt es.** Es gibt drei Wege, geordnet danach, -wie die meisten Menschen die Plattform tatsächlich nutzen: - -| Weg | Für wen | Ergebnis | -|---|---|---| -| **[AI Builder](/docs/build/ai-builder)** (primär) | Business-Anwender, Product Owner, jeder | Live-Metadaten in Ihrem Tenant, zur Genehmigung in der Warteschlange | -| **Console-Klickerstellung** (Fallback) | Admins, die Formulare bevorzugen | Dieselben Live-Metadaten | -| **[Vorlagen-Fork](/docs/build/templates)** (Entwicklerweg) | Ingenieure, die Code unter Versionskontrolle wollen | Ein TypeScript-Paket, ausgeliefert über den marketplace | - -Alle drei Wege erzeugen **dieselbe Artefaktform** — Pakete aus -Objekten, Feldern, Ansichten, Aktionen, Flows, Berechtigungen. Die Plattform -kümmert sich nicht darum, wie die Metadaten dorthin gelangt sind. - -## Das Plattform-Vokabular - -Jede App ist aus denselben Grundbausteinen zusammengesetzt. Lernen Sie diese einmal. - -| Konzept | Was es ist | Dokumentation | -|---|---|---| -| **[Package](/docs/build/packages)** | Die Organisationseinheit — `com.acme.crm`, versioniert, installierbar | Packages | -| **[Datenmodell](/docs/build/data)** | Objekte + Felder + Beziehungen + Zustandsautomaten | Data Model | -| **[Aktionen](/docs/build/interface/actions)** | Benannte Operationen, aufrufbar über REST, Console-Schaltflächen, Flows oder KI-Agenten | Actions | -| **[Flows](/docs/build/automation/flows)** | Deklarative Geschäftslogik (automatisch gestartet / geplant / manuell) | Flows | -| **[Agenten](/docs/build/agents)** | KI-Assistenten für Endanwender — Agent → Skill → Tool | Agents | -| **[Marketplace](/docs/build/marketplace)** | Fertige Pakete, die jeder mit einem Klick installieren kann | Marketplace | - -## Wo Sie beginnen sollten - -1. **Nur am Erkunden?** → Öffnen Sie die Console, starten Sie den [AI Builder](/docs/build/ai-builder), - sagen Sie *„Ich muss Kundensupport-Tickets mit Priorität, Status und Bearbeiter verfolgen."* - In weniger als 30 Sekunden haben Sie ein funktionierendes Objekt. - -2. **Ein echtes Produkt darauf aufbauen?** → Lesen Sie [Packages](/docs/build/packages) - und [Data Model](/docs/build/data), damit Sie verstehen, was die - KI generiert. Nutzen Sie die KI zum Entwerfen, verfeinern Sie von Hand oder per Chat - und committen Sie das Ergebnis. - -3. **Eine Salesforce-/Retool-App ablösen?** → Forken Sie die am besten passende - [marketplace-Vorlage](/docs/build/marketplace), entfernen Sie, was Sie - nicht brauchen, und bitten Sie die KI, die Lücken zu füllen. - -## Was Sie nie tun müssen - -- Einen REST-Endpunkt schreiben. Die Plattform generiert einen pro Objekt. -- Ein Console-Formular verdrahten. Das Formular wird aus dem Schema gerendert. -- RBAC-Prüfungen schreiben. Berechtigungen werden deklariert, nicht codiert. -- Eine Admin-Oberfläche bauen. Console + Account decken sowohl System- als auch Business-Administration ab. -- Typen generieren. `@objectstack/spec` leitet sie aus dem Schema ab. - -ObjectOS ist hierin bewusst meinungsstark: **Sobald Metadaten -existieren, erscheint jede Oberfläche (REST, Console, ObjectQL, Audit, KI-Tools) -kostenlos.** Deshalb funktioniert der AI Builder — er muss nur -Metadaten erzeugen, und die Plattform erledigt den Rest. diff --git a/content/docs/build/index.es.mdx b/content/docs/build/index.es.mdx deleted file mode 100644 index 339f55c..0000000 --- a/content/docs/build/index.es.mdx +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Construir -description: Cómo cobran vida las aplicaciones en ObjectOS — conversando con la IA, haciendo clic en la Console o bifurcando una plantilla. -translation: - source_sha: 59546f7a9524eea345e390f398a98223cc6d8f109070ac21cec910a2935bdf52 - guide_rev: 1 - mode: auto ---- - -En ObjectOS el cliente no escribe metadatos. **Describe lo que -quiere y la IA lo construye.** Existen tres caminos, ordenados según -cómo la mayoría de la gente usa realmente la plataforma: - -| Camino | Para quién es | Resultado | -|---|---|---| -| **[AI Builder](/docs/build/ai-builder)** (principal) | Usuarios de negocio, responsables de producto, cualquiera | Metadatos en vivo en tu tenant, en cola para aprobación | -| **Construcción por clics en Console** (alternativa) | Administradores que prefieren formularios | Los mismos metadatos en vivo | -| **[Bifurcación de plantilla](/docs/build/templates)** (camino para desarrolladores) | Ingenieros que quieren código bajo control de versiones | Un paquete de TypeScript distribuido a través del marketplace | - -Los tres caminos producen **la misma forma de artefacto** — paquetes de -objetos, campos, vistas, acciones, flujos y permisos. A la plataforma -no le importa cómo llegaron los metadatos hasta allí. - -## El vocabulario de la plataforma - -Toda aplicación se compone de las mismas primitivas. Apréndelas una vez. - -| Concepto | Qué es | Documentación | -|---|---|---| -| **[Package](/docs/build/packages)** | La unidad de organización — `com.acme.crm`, versionada e instalable | Packages | -| **[Data model](/docs/build/data)** | Objetos + campos + relaciones + máquinas de estado | Data Model | -| **[Actions](/docs/build/interface/actions)** | Operaciones con nombre invocables desde REST, botones de Console, flujos o agentes de IA | Actions | -| **[Flows](/docs/build/automation/flows)** | Lógica de negocio declarativa (autolanzada / programada / manual) | Flows | -| **[Agents](/docs/build/agents)** | Asistentes de IA para usuarios finales — Agent → Skill → Tool | Agents | -| **[Marketplace](/docs/build/marketplace)** | Paquetes ya hechos que cualquiera puede instalar con un solo clic | Marketplace | - -## Por dónde empezar - -1. **¿Solo estás explorando?** → Abre Console, inicia el [AI Builder](/docs/build/ai-builder), - di *"Necesito hacer seguimiento de tickets de soporte al cliente con prioridad, estado y responsable asignado."* - Tendrás un objeto funcional en menos de 30 segundos. - -2. **¿Construyendo un producto real sobre la plataforma?** → Lee [Packages](/docs/build/packages) - y [Data Model](/docs/build/data) para entender lo que la - IA está generando. Usa la IA para crear un borrador, refínalo a mano o por chat, - y confirma el resultado. - -3. **¿Reemplazando una aplicación de Salesforce/Retool?** → Bifurca la - [plantilla del marketplace](/docs/build/marketplace) más parecida, elimina lo - que no necesites y pídele a la IA que rellene los huecos. - -## Lo que nunca tendrás que hacer - -- Escribir un endpoint REST. La plataforma genera uno por objeto. -- Conectar un formulario de Console. El formulario se renderiza a partir del esquema. -- Escribir comprobaciones de RBAC. Los permisos se declaran, no se programan. -- Construir una interfaz de administración. Console + Account cubren tanto la administración del sistema como la de negocio. -- Generar tipos. `@objectstack/spec` los deriva del esquema. - -ObjectOS es deliberadamente firme en esto: **una vez que los metadatos -existen, cada superficie (REST, Console, ObjectQL, auditoría, herramientas de IA) -aparece de forma gratuita.** Por eso funciona el AI Builder — solo necesita -producir metadatos, y la plataforma se encarga del resto. diff --git a/content/docs/build/index.fr.mdx b/content/docs/build/index.fr.mdx deleted file mode 100644 index 7708f92..0000000 --- a/content/docs/build/index.fr.mdx +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Créer -description: Comment les applications prennent vie dans ObjectOS — en discutant avec l'IA, en cliquant dans Console ou en forkant un modèle. -translation: - source_sha: 59546f7a9524eea345e390f398a98223cc6d8f109070ac21cec910a2935bdf52 - guide_rev: 1 - mode: auto ---- - -Dans ObjectOS, le client n'écrit pas de métadonnées. **Il décrit ce -qu'il veut et l'IA le construit.** Trois approches existent, classées -selon la manière dont la plupart des gens utilisent réellement la -plateforme : - -| Approche | Pour qui | Résultat | -|---|---|---| -| **[AI Builder](/docs/build/ai-builder)** (principale) | Utilisateurs métier, product owners, tout le monde | Métadonnées en direct dans votre tenant, en attente d'approbation | -| **Construction par clic dans Console** (alternative) | Administrateurs qui préfèrent les formulaires | Les mêmes métadonnées en direct | -| **[Fork de modèle](/docs/build/templates)** (voie développeur) | Ingénieurs qui veulent du code sous contrôle de version | Un package TypeScript livré via le marketplace | - -Les trois approches produisent **la même forme d'artefact** — des -packages d'objets, de champs, de vues, d'actions, de flows et de -permissions. La plateforme se moque de la manière dont les métadonnées -ont été créées. - -## Le vocabulaire de la plateforme - -Chaque application est composée des mêmes primitives. Apprenez-les une -bonne fois. - -| Concept | Ce que c'est | Doc | -|---|---|---| -| **[Package](/docs/build/packages)** | L'unité d'organisation — `com.acme.crm`, versionné, installable | Packages | -| **[Data model](/docs/build/data)** | Objets + champs + relations + machines à états | Data Model | -| **[Actions](/docs/build/interface/actions)** | Opérations nommées appelables depuis REST, boutons Console, flows ou agents IA | Actions | -| **[Flows](/docs/build/automation/flows)** | Logique métier déclarative (autolancée / planifiée / manuelle) | Flows | -| **[Agents](/docs/build/agents)** | Assistants IA pour l'utilisateur final — Agent → Skill → Tool | Agents | -| **[Marketplace](/docs/build/marketplace)** | Packages prêts à l'emploi installables par tous en un clic | Marketplace | - -## Par où commencer - -1. **Vous explorez simplement ?** → Ouvrez Console, lancez l'[AI Builder](/docs/build/ai-builder), - dites *« J'ai besoin de suivre les tickets de support client avec priorité, statut et assigné. »* - Vous aurez un objet fonctionnel en moins de 30 secondes. - -2. **Vous construisez un véritable produit par-dessus ?** → Lisez [Packages](/docs/build/packages) - et [Data Model](/docs/build/data) pour comprendre ce que - l'IA génère. Utilisez l'IA pour ébaucher, affinez à la main ou par - chat, puis validez le résultat. - -3. **Vous remplacez une application Salesforce/Retool ?** → Forkez le - [modèle marketplace](/docs/build/marketplace) le plus proche, retirez ce - dont vous n'avez pas besoin et demandez à l'IA de combler les manques. - -## Ce que vous n'aurez jamais à faire - -- Écrire un endpoint REST. La plateforme en génère un par objet. -- Câbler un formulaire Console. Le formulaire est rendu à partir du schéma. -- Écrire des vérifications RBAC. Les permissions sont déclarées, pas codées. -- Construire une interface d'administration. Console + Account couvrent à la fois l'administration système et métier. -- Générer des types. `@objectstack/spec` les dérive à partir du schéma. - -ObjectOS est volontairement opinionné sur ce point : **dès lors que les -métadonnées existent, chaque surface (REST, Console, ObjectQL, audit, -outils IA) apparaît gratuitement.** C'est pourquoi l'AI Builder -fonctionne — il lui suffit de produire des métadonnées, et la -plateforme s'occupe du reste. diff --git a/content/docs/build/index.ja.mdx b/content/docs/build/index.ja.mdx deleted file mode 100644 index 845c9e5..0000000 --- a/content/docs/build/index.ja.mdx +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: 構築 -description: ObjectOS でアプリが生まれる仕組み — AI とチャットする、Console でクリックする、あるいはテンプレートをフォークする。 -translation: - source_sha: 59546f7a9524eea345e390f398a98223cc6d8f109070ac21cec910a2935bdf52 - guide_rev: 1 - mode: auto ---- - -ObjectOS では顧客がメタデータを記述することはありません。**やりたいことを説明すれば、AI がそれを構築します。** 多くの人が実際にプラットフォームを利用する順に、3 つの方法があります。 - -| 方法 | 対象ユーザー | 成果物 | -|---|---|---| -| **[AI Builder](/docs/build/ai-builder)**（メイン） | ビジネスユーザー、プロダクトオーナー、誰でも | テナント内のライブメタデータ。承認待ちのキューに入る | -| **Console によるクリック構築**（代替手段） | フォーム操作を好む管理者 | 同じライブメタデータ | -| **[テンプレートのフォーク](/docs/build/templates)**（開発者向け） | コードをソース管理下に置きたいエンジニア | marketplace 経由で配布される TypeScript パッケージ | - -3 つの方法はいずれも **同じ成果物の形** を生み出します — オブジェクト、フィールド、ビュー、アクション、フロー、権限のパッケージです。プラットフォームはメタデータがどのように作られたかを問いません。 - -## プラットフォームの語彙 - -すべてのアプリは同じプリミティブから構成されます。これらを一度学んでおきましょう。 - -| 概念 | 内容 | ドキュメント | -|---|---|---| -| **[Package](/docs/build/packages)** | 編成の単位 — `com.acme.crm`、バージョン管理され、インストール可能 | Packages | -| **[Data model](/docs/build/data)** | オブジェクト + フィールド + リレーションシップ + ステートマシン | Data Model | -| **[Actions](/docs/build/interface/actions)** | REST、Console のボタン、フロー、AI エージェントから呼び出せる名前付きの操作 | Actions | -| **[Flows](/docs/build/automation/flows)** | 宣言的なビジネスロジック（自動起動 / スケジュール / 手動） | Flows | -| **[Agents](/docs/build/agents)** | エンドユーザー向けの AI アシスタント — Agent → Skill → Tool | Agents | -| **[Marketplace](/docs/build/marketplace)** | 誰でもワンクリックでインストールできる既製のパッケージ | Marketplace | - -## どこから始めるか - -1. **まずは試してみたい?** → Console を開き、[AI Builder](/docs/build/ai-builder) を起動して、 - *「優先度、ステータス、担当者を持つカスタマーサポートのチケットを管理したい」* と言ってみましょう。 - 30 秒もかからずに動作するオブジェクトが手に入ります。 - -2. **本格的なプロダクトをその上に構築する?** → [Packages](/docs/build/packages) - と [Data Model](/docs/build/data) を読んで、AI が生成している内容を理解しましょう。 - AI で下書きを作り、手作業やチャットで調整し、結果をコミットします。 - -3. **Salesforce / Retool のアプリを置き換える?** → 最も近い - [marketplace テンプレート](/docs/build/marketplace) をフォークし、不要なものを削ぎ落とし、 - 足りない部分を AI に埋めてもらいましょう。 - -## 一切やらなくてよいこと - -- REST エンドポイントの記述。プラットフォームがオブジェクトごとに 1 つ生成します。 -- Console フォームの配線。フォームはスキーマからレンダリングされます。 -- RBAC チェックの記述。権限はコードではなく宣言されます。 -- 管理 UI の構築。Console + Account がシステム管理とビジネス管理の両方をカバーします。 -- 型の生成。`@objectstack/spec` がスキーマから型を導出します。 - -ObjectOS は意図的にこの点について方針を明確にしています。**メタデータが存在すれば、あらゆる接点（REST、Console、ObjectQL、監査、AI ツール）が自動的に現れます。** だからこそ AI Builder が機能するのです — AI はメタデータを生成しさえすればよく、残りはプラットフォームが処理します。 diff --git a/content/docs/build/index.ko.mdx b/content/docs/build/index.ko.mdx deleted file mode 100644 index ffecb8f..0000000 --- a/content/docs/build/index.ko.mdx +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: 빌드 -description: ObjectOS에서 앱이 만들어지는 방식 — AI와 대화하거나, Console에서 클릭하거나, 템플릿을 포크하여. -translation: - source_sha: 59546f7a9524eea345e390f398a98223cc6d8f109070ac21cec910a2935bdf52 - guide_rev: 1 - mode: auto ---- - -ObjectOS에서 고객은 메타데이터를 작성하지 않습니다. **원하는 것을 -설명하면 AI가 만들어 줍니다.** 대부분의 사람들이 실제로 플랫폼을 -사용하는 순서에 따라 세 가지 경로가 있습니다: - -| 경로 | 대상 | 결과물 | -|---|---|---| -| **[AI Builder](/docs/build/ai-builder)** (주요) | 비즈니스 사용자, 제품 책임자, 누구나 | 테넌트의 라이브 메타데이터, 승인 대기열에 등록 | -| **Console 클릭 빌드** (대안) | 폼을 선호하는 관리자 | 동일한 라이브 메타데이터 | -| **[템플릿 포크](/docs/build/templates)** (개발 경로) | 소스 관리 하에 코드를 두고자 하는 엔지니어 | marketplace를 통해 배포되는 TypeScript 패키지 | - -세 가지 경로 모두 **동일한 형태의 산출물** — 객체, 필드, 뷰, 액션, -플로우, 권한의 패키지를 생성합니다. 플랫폼은 메타데이터가 어떻게 -만들어졌는지 신경 쓰지 않습니다. - -## 플랫폼 용어 - -모든 앱은 동일한 기본 요소로 구성됩니다. 이것들을 한 번만 익혀 두세요. - -| 개념 | 무엇인가 | 문서 | -|---|---|---| -| **[Package](/docs/build/packages)** | 조직화의 단위 — `com.acme.crm`, 버전 관리, 설치 가능 | Packages | -| **[Data model](/docs/build/data)** | 객체 + 필드 + 관계 + 상태 머신 | Data Model | -| **[Actions](/docs/build/interface/actions)** | REST, Console 버튼, 플로우, AI 에이전트에서 호출 가능한 명명된 작업 | Actions | -| **[Flows](/docs/build/automation/flows)** | 선언적 비즈니스 로직 (자동 실행 / 예약 / 수동) | Flows | -| **[Agents](/docs/build/agents)** | 최종 사용자 AI 어시스턴트 — Agent → Skill → Tool | Agents | -| **[Marketplace](/docs/build/marketplace)** | 누구나 원클릭으로 설치할 수 있는 기성 패키지 | Marketplace | - -## 어디서 시작할까 - -1. **그냥 둘러보는 중인가요?** → Console을 열고 [AI Builder](/docs/build/ai-builder)를 시작하여, - *"우선순위, 상태, 담당자가 있는 고객 지원 티켓을 추적하고 싶어요."* 라고 말해 보세요. - 30초 안에 작동하는 객체를 갖게 됩니다. - -2. **그 위에 실제 제품을 구축하나요?** → AI가 생성하는 것을 이해할 수 - 있도록 [Packages](/docs/build/packages)와 [Data Model](/docs/build/data)을 - 읽어 보세요. AI로 초안을 작성하고, 직접 또는 대화로 다듬은 뒤, - 결과를 커밋하세요. - -3. **Salesforce/Retool 앱을 대체하나요?** → 가장 가까운 - [marketplace 템플릿](/docs/build/marketplace)을 포크하고, 필요 없는 것을 - 제거한 뒤, AI에게 빈 부분을 채워 달라고 요청하세요. - -## 절대 하지 않아도 되는 일 - -- REST 엔드포인트 작성. 플랫폼이 객체마다 하나씩 생성합니다. -- Console 폼 연결. 폼은 스키마로부터 렌더링됩니다. -- RBAC 검사 작성. 권한은 코딩되는 것이 아니라 선언됩니다. -- 관리자 UI 구축. Console + Account가 시스템 및 비즈니스 관리 모두를 다룹니다. -- 타입 생성. `@objectstack/spec`이 스키마로부터 타입을 도출합니다. - -ObjectOS는 의도적으로 이 점에 대해 확고합니다: **메타데이터가 일단 -존재하면, 모든 표면(REST, Console, ObjectQL, 감사, AI 도구)이 -무료로 나타납니다.** 그렇기 때문에 AI Builder가 작동하는 것입니다 — -메타데이터만 생성하면 되고, 나머지는 플랫폼이 처리합니다. diff --git a/content/docs/build/index.mdx b/content/docs/build/index.mdx index 94c73f8..d2cc12a 100644 --- a/content/docs/build/index.mdx +++ b/content/docs/build/index.mdx @@ -4,8 +4,11 @@ seoTitle: "Build Apps: AI Chat, Studio Forms, or Templates" description: How apps come to life in ObjectOS — by chatting with AI, by clicking through forms in Studio, or by forking a template. --- -In ObjectOS the customer doesn't write metadata. **They describe what -they want and the AI builds it.** Three paths exist, in order of how +Building in ObjectOS is authoring your [ontology](/docs/ontology) — its +core (objects and fields, relations, actions, permissions, flows, agents) +and the projections people see it through (views, dashboards, apps). +Most people don't write that metadata by hand: **they describe what they +want and the AI Builder writes it.** Three paths exist, in order of how most people actually use the platform: | Path | Who's it for | Output | @@ -14,9 +17,14 @@ most people actually use the platform: | **Click-build** (fallback) | Admins who prefer Studio's forms | The same live metadata | | **[Template fork](/docs/build/templates)** (dev path) | Engineers who want code under source control | A TypeScript package shipped via the marketplace | -All three paths produce **the same artifact shape** — packages of -objects, fields, views, actions, flows, permissions. The platform -doesn't care how the metadata got there. +All three paths author **the same ontology** — the same objects, fields, +relations, actions, permissions and flows, with the same projections — and +every path passes the same validation gate before anything runs: the +`@objectstack/spec` schemas and the authoring rules `os validate` runs, +which the runtime also applies to every metadata write from the AI +Builder or Studio. See +[Validating Metadata](https://objectstack.ai/docs/deployment/validating-metadata) +in the ObjectStack docs. ## The platform vocabulary @@ -27,7 +35,8 @@ Every app is composed from the same primitives. Learn these once. | **[Package](/docs/build/packages)** | The unit of organization — `com.acme.crm`, versioned, installable | Packages | | **[Data model](/docs/build/data)** | Objects + fields + relationships + state machines | Data Model | | **[Interface](/docs/build/interface)** | Apps, views, forms, dashboards, and pages — what your users see | Interface | -| **[Actions](/docs/build/interface/actions)** | Named operations callable from REST, buttons, flows, or AI agents | Actions | +| **[Actions](/docs/build/interface/actions)** | Named operations — callable from REST and from buttons, and by AI agents once you expose them; one can start a flow | Actions | +| **[Permissions](/docs/configure/permissions)** | Who may read, create, edit and delete what — permission sets, record access, field-level security | Permissions | | **[Flows](/docs/build/automation/flows)** | Declarative business logic (autolaunched / scheduled / manual) | Flows | | **[Agents](/docs/build/agents)** | End-user AI assistants — Agent → Skill → Tool | Agents | | **[Marketplace](/docs/build/marketplace)** | Ready-made packages anyone can install in one click | Marketplace | diff --git a/content/docs/build/index.zh-Hans.mdx b/content/docs/build/index.zh-Hans.mdx deleted file mode 100644 index 9b1cc83..0000000 --- a/content/docs/build/index.zh-Hans.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: 构建 -description: 在 ObjectOS 里应用是怎么诞生的 —— 跟 AI 对话、在 Console 里点击，或者 fork 一个模板。 -translation: - source_sha: 59546f7a9524eea345e390f398a98223cc6d8f109070ac21cec910a2935bdf52 - guide_rev: 1 - mode: auto ---- - -在 ObjectOS 中，客户不写元数据。**他们描述想要什么，AI 来构建。**有三条路径，按大多数人实际使用平台的顺序排列： - -| 路径 | 适合谁 | 产出 | -|---|---|---| -| **[AI Builder](/docs/build/ai-builder)**（主路径） | 业务用户、产品负责人、任何人 | 你租户内的实时元数据，等待审批 | -| **Console 点击构建**（兜底） | 偏好表单的管理员 | 同样的实时元数据 | -| **[模板 Fork](/docs/build/templates)**（开发者路径） | 想要代码进版本管理的工程师 | 通过 marketplace 分发的一个 TypeScript 包 | - -三条路径产出**同一种产物形态** —— 对象、字段、视图、Action、流程、权限的打包。平台不关心元数据是怎么来的。 - -## 平台词汇表 - -每个应用都由同样的原语组成。学一次就好。 - -| 概念 | 是什么 | 文档 | -|---|---|---| -| **[包](/docs/build/packages)** | 组织单位 —— `com.acme.crm`，带版本，可安装 | Packages | -| **[数据模型](/docs/build/data)** | 对象 + 字段 + 关系 + 状态机 | Data Model | -| **[界面](/docs/build/interface)** | 应用、视图、表单、仪表盘与页面 —— 用户看到的一切 | Interface | -| **[Actions](/docs/build/interface/actions)** | 命名操作，可被 REST、Console 按钮、流程或 AI Agent 调用 | Actions | -| **[流程](/docs/build/automation/flows)** | 声明式业务逻辑（自动启动 / 定时 / 手动） | Flows | -| **[Agents](/docs/build/agents)** | 面向终端用户的 AI 助手 —— Agent → Skill → Tool | Agents | -| **[marketplace](/docs/build/marketplace)** | 一键安装的现成包 | Marketplace | - -## 从哪里开始 - -1. **只是探索？** → 打开 Console，启动 [AI Builder](/docs/build/ai-builder)， - 说一句*"我需要跟踪客户支持工单，带优先级、状态和负责人。"* - 30 秒内你就有一个能用的对象。 - -2. **在上面构建真实产品？** → 阅读 [Packages](/docs/build/packages) - 和 [Data Model](/docs/build/data)，理解 AI 在生成什么。 - 用 AI 起草，手动或对话方式打磨，提交结果。 - -3. **替换 Salesforce/Retool 应用？** → Fork 最接近的 - [marketplace 模板](/docs/build/marketplace)，去掉不需要的部分， - 让 AI 补上空缺。 - -## 你永远不需要做的事 - -- 写 REST 端点。平台为每个对象自动生成一个。 -- 接 Console 表单。表单从 schema 渲染。 -- 写 RBAC 检查。权限是声明的，不是写代码。 -- 构建管理 UI。Console + Account 覆盖系统和业务两类管理。 -- 生成类型。`@objectstack/spec` 从 schema 派生它们。 - -ObjectOS 在这点上是有意为之的：**一旦元数据存在，所有界面（REST、Console、ObjectQL、审计、AI 工具）就自动出现。**这就是 AI Builder 能跑通的原因 —— 它只需要产出元数据，剩下的平台全包了。 diff --git a/content/docs/build/index.zh-Hant.mdx b/content/docs/build/index.zh-Hant.mdx deleted file mode 100644 index c3946cc..0000000 --- a/content/docs/build/index.zh-Hant.mdx +++ /dev/null @@ -1,57 +0,0 @@ ---- -# @generated zh-Hant from zh-Hans -- do not edit. Edit the English source, then regenerate: pnpm --filter @objectos/docs gen:zh-hant -title: 構建 -description: 在 ObjectOS 裡應用是怎麼誕生的 —— 跟 AI 對話、在 Console 裡點選，或者 fork 一個模板。 -translation: - source_sha: 59546f7a9524eea345e390f398a98223cc6d8f109070ac21cec910a2935bdf52 - guide_rev: 1 - mode: auto ---- - -在 ObjectOS 中，客戶不寫後設資料。**他們描述想要什麼，AI 來構建。**有三條路徑，按大多數人實際使用平臺的順序排列： - -| 路徑 | 適合誰 | 產出 | -|---|---|---| -| **[AI Builder](/docs/build/ai-builder)**（主路徑） | 業務使用者、產品負責人、任何人 | 你租戶內的即時後設資料，等待審批 | -| **Console 點選構建**（兜底） | 偏好表單的管理員 | 同樣的即時後設資料 | -| **[模板 Fork](/docs/build/templates)**（開發者路徑） | 想要程式碼進版本管理的工程師 | 通過 marketplace 分發的一個 TypeScript 包 | - -三條路徑產出**同一種產物形態** —— 物件、欄位、檢視、Action、流程、許可權的打包。平臺不關心後設資料是怎麼來的。 - -## 平臺詞彙表 - -每個應用都由同樣的原語組成。學一次就好。 - -| 概念 | 是什麼 | 文件 | -|---|---|---| -| **[包](/docs/build/packages)** | 組織單位 —— `com.acme.crm`，帶版本，可安裝 | Packages | -| **[資料模型](/docs/build/data)** | 物件 + 欄位 + 關係 + 狀態機 | Data Model | -| **[介面](/docs/build/interface)** | 應用、檢視、表單、儀表盤與頁面 —— 使用者看到的一切 | Interface | -| **[Actions](/docs/build/interface/actions)** | 命名操作，可被 REST、Console 按鈕、流程或 AI Agent 呼叫 | Actions | -| **[流程](/docs/build/automation/flows)** | 宣告式業務邏輯（自動啟動 / 定時 / 手動） | Flows | -| **[Agents](/docs/build/agents)** | 面向終端使用者的 AI 助手 —— Agent → Skill → Tool | Agents | -| **[marketplace](/docs/build/marketplace)** | 一鍵安裝的現成包 | Marketplace | - -## 從哪裡開始 - -1. **只是探索？** → 開啟 Console，啟動 [AI Builder](/docs/build/ai-builder)， - 說一句*"我需要跟蹤客戶支援工單，帶優先順序、狀態和負責人。"* - 30 秒內你就有一個能用的物件。 - -2. **在上面構建真實產品？** → 閱讀 [Packages](/docs/build/packages) - 和 [Data Model](/docs/build/data)，理解 AI 在生成什麼。 - 用 AI 起草，手動或對話方式打磨，提交結果。 - -3. **替換 Salesforce/Retool 應用？** → Fork 最接近的 - [marketplace 模板](/docs/build/marketplace)，去掉不需要的部分， - 讓 AI 補上空缺。 - -## 你永遠不需要做的事 - -- 寫 REST 端點。平臺為每個物件自動生成一個。 -- 接 Console 表單。表單從 schema 渲染。 -- 寫 RBAC 檢查。許可權是宣告的，不是寫程式碼。 -- 構建管理 UI。Console + Account 覆蓋系統和業務兩類管理。 -- 生成型別。`@objectstack/spec` 從 schema 派生它們。 - -ObjectOS 在這點上是有意為之的：**一旦後設資料存在，所有介面（REST、Console、ObjectQL、審計、AI 工具）就自動出現。**這就是 AI Builder 能跑通的原因 —— 它只需要產出後設資料，剩下的平臺全包了。 diff --git a/content/docs/build/interface/actions.mdx b/content/docs/build/interface/actions.mdx index f4bffc2..ee88de4 100644 --- a/content/docs/build/interface/actions.mdx +++ b/content/docs/build/interface/actions.mdx @@ -9,7 +9,8 @@ it appears as: - a **REST endpoint** at `/api/v1/actions//` - a **button** on the record detail page -- an **AI tool** (`action_`) for Agents and the AI Builder +- an **AI tool** (`action_`) for Agents and the AI Builder — once + you expose it to AI (`ai.exposed`, [below](#from-an-ai-agent)) You don't repeat yourself across three surfaces. One declaration; three ways to call it. An action can also start a [flow](/docs/build/automation/flows) @@ -40,15 +41,25 @@ export const approveInvoice = Action.create({ // only show the button when the record is still pending visible: 'record.status == "pending"', - // what it does — a sandboxed script body + // expose it to agents and the AI Builder as `action_approve_invoice` + ai: { + exposed: true, + description: 'Approve a pending invoice, recording the approver and an optional note.', + }, + + // what it does — a sandboxed script body. `input` is the params bag; + // `ctx.record` is a read-only snapshot, so the write goes through `ctx.api`, + // which needs the `api.write` capability type: 'script', body: { language: 'js', + capabilities: ['api.write'], source: ` - await ctx.data.update('invoice', input.id, { + await ctx.api.object('invoice').update({ + id: ctx.recordId, status: 'approved', approved_by: ctx.user.id, - approved_at: now(), + approved_at: new Date().toISOString(), approval_note: input.note, }); `, @@ -60,7 +71,8 @@ After `os dev` recompiles: - `POST /api/v1/actions/invoice/approve_invoice` works - The Invoice record page shows an **Approve Invoice** button -- The AI assistant can call `action_approve_invoice` if its skills allow +- The AI assistant can call `action_approve_invoice` — it is exposed to + AI — if its skills allow ## Action types @@ -68,7 +80,7 @@ The `type` field decides what the action does: | `type` | What runs | Use for | |---|---|---| -| `script` | A `body` — an L1 formula expression or sandboxed L2 JavaScript | Most cases — server-side logic, auditable + AI-callable | +| `script` | A `body` — an L1 formula expression or sandboxed L2 JavaScript | Most cases — server-side logic, auditable, and AI-callable once exposed | | `api` | An HTTP call to a `target` endpoint (`method`, `bodyExtra`) | Reusing data-API or platform endpoints | | `flow` | Runs the flow named in `target` | Multi-step business processes | | `url` | Navigates to the `target` URL | Deep links, redirect-style actions | @@ -89,8 +101,9 @@ Action.create({ }); ``` -Types other than `script` require a `target`. Whichever type, the action -is the same first-class citizen on every surface. +Types other than `script` require a `target`. Whichever type, it is one +declaration — but `url`, `modal` and `form` actions run only in the UI, so +they never become AI tools. ## Calling an action @@ -147,25 +160,40 @@ Action.create({ ### From an AI Agent -If `approve_invoice` is in any skill the agent has, the LLM can call -it. Inputs come from the conversation; permissions are enforced as if -the user invoked it directly. +An action reaches agents only when its author exposes it to AI: +`ai: { exposed: true }` with an `ai.description` of at least 40 +characters, as in the example above, on a type that runs without a UI +(`script`, `flow` or `api`). Exposed, it is the `action_` tool in +ObjectOS's own agents and the AI Builder, and `run_action` for an +[MCP client](/docs/configure/mcp). Unexposed, it is invisible to agents +and refused if called. + +If `approve_invoice` is exposed and in a skill the agent has, the LLM can +call it. Inputs come from the conversation; the same invoke-time checks +apply as if the user had pressed the button. > *"Approve invoice INV-2042 with note 'verified by phone.'"* ## Permissions -Actions run with the calling user's permissions. The platform checks: +Who may run an action is checked as the caller, when it is invoked — +the same way over REST, from a button, and from an agent: -1. **Object permissions** — the user's [permission sets](/docs/configure/permissions/permission-sets) - must grant the object-level access the action needs (e.g. update). -2. **Field permissions** — for any field the action writes, the user - must have write access (FLS). -3. **UI gating** — the `visible` and `disabled` predicates (CEL, +1. **`requiredPermissions`** — capabilities the caller's + [permission sets](/docs/configure/permissions/permission-sets) must + hold. A caller missing one gets `403`. +2. **The subject record** — it is loaded as the caller. A record the + caller cannot read is answered as not found. +3. **AI exposure** — an agent reaches only actions exposed to AI. +4. **UI gating** — the `visible` and `disabled` predicates (CEL, evaluated against `record`, `os.user`, and params) control whether the button renders or is greyed out. -Failed permission checks return `403` with a `PERMISSION_DENIED` error. +What the action then does is trusted app code. A `script` body's reads +and writes run with the app's authority: record access and field-level +security do **not** bound them. A `flow` action follows the flow's +`runAs`. So declare `requiredPermissions` for anything sensitive, and +treat writing an action as a code-review-worthy act. ## Built-in actions diff --git a/content/docs/build/templates.de.mdx b/content/docs/build/templates.de.mdx deleted file mode 100644 index 1a9c396..0000000 --- a/content/docs/build/templates.de.mdx +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: Vorlagen -description: Forkbare Starterpakete — `todo`, `contracts`, `procurement`, `helpdesk` und mehr. -translation: - source_sha: 25ae072d41ab70627e03786cf2c69aa5a017f481c778b4d780c52201128f07e1 - guide_rev: 1 - mode: auto ---- - -Vorlagen sind **forkbare Starterpakete**. Jede einzelne ist eine echte, -ausgeformte App, die du mit einem Klick aus dem marketplace installieren -oder mit der CLI klonen kannst, um eine TypeScript-Codebasis zum Erweitern -zu erhalten. - -Vorlagen existieren aus zwei Gründen: - -1. **Zeigen statt erzählen** — eine funktionierende App mit mehreren - Objekten liest sich schneller als Dokumentation. -2. **Engineering-Teams einen Ausgangspunkt geben** — wenn du Code unter - Versionskontrolle haben möchtest und nicht nur KI-generierte Metadaten - in deiner DB. - -## Was im Standardkatalog enthalten ist - -| Vorlage | Domäne | Forkbarer Starter für… | -|---|---|---| -| **`todo`** | Aufgaben & Projekte | Jedes „zu erledigende Dinge, irgendwie gruppiert"-Tool | -| **`contracts`** | CLM mit KI-Klauselextraktion | Genehmigungen + Dokument-KI | -| **`procurement`** | Lieferanten, Bestellungen, 3-Wege-Abgleich | Genehmigungsketten + Wareneingang | -| **`compliance`** | SOC 2 / ISO 27001 Controls | Workflows zur Nachweissammlung | -| **`helpdesk`** | KI-zentrierter Kundensupport | Tickets + SLAs + KI-Co-Pilot | -| **`content`** | Redaktionskalender + Kanal-ROI | Lebenszyklus + Kennzahlen | -| **`hr`** | Verzeichnis, Organigramm, Abwesenheit | Personenzentrierte Apps | -| **`project`** | Projekt- / Aufgaben- / Meilenstein-Tracking | PM-Tools | - -Quelle: [github.com/objectstack-ai/templates](https://github.com/objectstack-ai/templates). -Apache-2.0. Forke ohne zu fragen. - -## In 30 Sekunden installieren (kein Code) - -In der Console: - -1. Öffne **Marketplace** → suche nach der Vorlage. -2. Klicke auf **Install**. -3. Aktualisiere die Seite — die neue App erscheint in deiner Navigation. - -Fertig. Datensätze, Ansichten, Flows, Berechtigungen — alles live. - -## Als Codebasis forken (für Engineers) - -```bash -pnpm dlx @objectstack/cli create my-app --template todo -cd my-app -pnpm install -pnpm dev # http://localhost:4002 -``` - -Der Klon ist ein eigenständiges pnpm-Paket — `*.object.ts`-, -`*.view.ts`-, `*.flow.ts`-Dateien, die du bearbeiten, linten, testen und -committen kannst. Wenn du zufrieden bist: - -```bash -pnpm build -os package publish # → dein marketplace -``` - -Kunden, die deinen Fork installieren, erhalten **deine** Marke und -**deine** Anpassungen. - -## Vorlagen-Charta (der soziale Vertrag) - -Jede Vorlage bringt eine `CHARTER.md` mit, die ihren Umfang und ihre -harten Grenzen deklariert — typischerweise: ≤ 6 Geschäftsobjekte, -≤ 2.500 LOC unter `src/`, eine App, ein Standard-Locale. Die Charta -existiert, damit Vorlagen **Vorlagen** bleiben und keine halbfertigen -Produkte werden. Wenn ein Fork über diese Grenzen hinauswächst, liefere -ihn als neue Vorlage aus und blähe keine bestehende auf. - -Siehe die vorgelagerte [TEMPLATE_GUIDE.md](https://github.com/objectstack-ai/templates/blob/main/TEMPLATE_GUIDE.md) -für das Dateisuffix-Protokoll (`*.object.ts`, `*.state.ts`, `*.hook.ts`, …), -die Erstellungsreihenfolge (Objekte → State → Hooks → Ansichten → Flows → …) -und die polymorphen Plattformdienste (`sys_comment`, `sys_attachment`, -`sys_audit_log`), die du wiederverwenden solltest, anstatt sie neu zu erfinden. - -## Wähle einen Ausgangspunkt - -| Wenn du Folgendes baust… | Forke dies | Warum | -|---|---|---| -| Jedes interne Tool, das „Sachen" trackt | `todo` | Kleinste, sauberste Demonstration aller Primitive | -| Alles mit Genehmigungsketten | `procurement` oder `contracts` | Echte Genehmigungsprozesse verdrahtet | -| Alles Kundenorientierte mit KI | `helpdesk` | Agent- + Ticket-Co-Pilot-Muster | -| Einen Workflow für regulierte Branchen | `compliance` | Audit + Nachweise + Control-Mapping | -| Eine Personen- / Organigramm-App | `hr` | Verzeichnis + Berichtsstruktur | - -## AI Builder + Vorlagen zusammen - -Du kannst eine Vorlage forken und **trotzdem** den AI Builder darauf -anwenden. Installiere `helpdesk` und sage dann: - -> *„Füge ein `csat_score`-Integer-Feld zu `hd_ticket` hinzu, Bereich 1–5, -> frage beim Schließen danach."* - -Der AI Builder erweitert das installierte Paket direkt vor Ort. Pushe die -Änderung mit `os package export` ins Quell-Repository. - -## Wie es weitergeht - -- [AI Builder](/docs/build/ai-builder) — erweitere jede Vorlage per Chat -- [Packages](/docs/build/packages) — was eine Vorlage tatsächlich ist -- [Marketplace](/docs/build/marketplace) — verteile deinen Fork -- [Quickstart](/docs/quickstart) — vollständiger End-to-End-Durchlauf des Entwicklerpfads diff --git a/content/docs/build/templates.es.mdx b/content/docs/build/templates.es.mdx deleted file mode 100644 index ed1df6e..0000000 --- a/content/docs/build/templates.es.mdx +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: Plantillas -description: Paquetes de inicio bifurcables — `todo`, `contracts`, `procurement`, `helpdesk` y más. -translation: - source_sha: 25ae072d41ab70627e03786cf2c69aa5a017f481c778b4d780c52201128f07e1 - guide_rev: 1 - mode: auto ---- - -Las plantillas son **paquetes de inicio bifurcables**. Cada una es una -aplicación real y bien definida que puedes instalar desde el marketplace con un -clic, o clonar con la CLI para obtener una base de código en TypeScript que -puedes ampliar. - -Las plantillas existen por dos razones: - -1. **Mostrar, no contar** — una aplicación funcional de varios objetos se lee - más rápido que la documentación. -2. **Dar a los equipos de ingeniería un punto de partida** — cuando quieres - código bajo control de versiones, no solo metadatos generados por IA en tu - base de datos. - -## Qué incluye el catálogo predeterminado - -| Plantilla | Dominio | Punto de partida bifurcable para… | -|---|---|---| -| **`todo`** | Tareas y proyectos | Cualquier herramienta de "cosas por hacer, agrupadas de algún modo" | -| **`contracts`** | CLM con extracción de cláusulas por IA | Aprobaciones + IA de documentos | -| **`procurement`** | Proveedores, OC, conciliación a tres bandas | Cadenas de aprobación + recepción | -| **`compliance`** | Controles SOC 2 / ISO 27001 | Flujos de recopilación de evidencias | -| **`helpdesk`** | Soporte al cliente con IA en primer lugar | Tickets + SLA + copiloto de IA | -| **`content`** | Calendario editorial + ROI por canal | Ciclo de vida + métricas | -| **`hr`** | Directorio, organigrama, ausencias | Aplicaciones centradas en las personas | -| **`project`** | Seguimiento de proyectos / tareas / hitos | Herramientas de gestión de proyectos | - -Fuente: [github.com/objectstack-ai/templates](https://github.com/objectstack-ai/templates). -Apache-2.0. Bifurca sin pedir permiso. - -## Instala en 30 segundos (sin código) - -En Console: - -1. Abre **Marketplace** → busca la plantilla. -2. Haz clic en **Install**. -3. Actualiza — la nueva aplicación aparece en tu navegación. - -Listo. Registros, vistas, flujos, permisos — todo activo. - -## Bifurca como base de código (para ingenieros) - -```bash -pnpm dlx @objectstack/cli create my-app --template todo -cd my-app -pnpm install -pnpm dev # http://localhost:4002 -``` - -El clon es un paquete pnpm autónomo — archivos `*.object.ts`, -`*.view.ts`, `*.flow.ts` que puedes editar, lintear, probar y confirmar. Cuando -estés conforme: - -```bash -pnpm build -os package publish # → tu marketplace -``` - -Los clientes que instalen tu bifurcación obtienen **tu** marca y **tus** -modificaciones. - -## Estatuto de la plantilla (el contrato social) - -Cada plantilla incluye un `CHARTER.md` que declara su alcance y sus límites -estrictos — normalmente: ≤ 6 objetos de negocio, ≤ 2.500 líneas de código bajo -`src/`, una aplicación, una configuración regional predeterminada. El estatuto -existe para que las plantillas sigan siendo **plantillas**, no productos a medio -terminar. Si una bifurcación supera estos límites, publícala como una plantilla -nueva; no infles una existente. - -Consulta el [TEMPLATE_GUIDE.md](https://github.com/objectstack-ai/templates/blob/main/TEMPLATE_GUIDE.md) -original para conocer el protocolo de sufijos de archivo (`*.object.ts`, `*.state.ts`, `*.hook.ts`, …), -la secuencia de creación (objects → state → hooks → views → flows → …), -y los servicios polimórficos de la plataforma (`sys_comment`, `sys_attachment`, -`sys_audit_log`) que deberías reutilizar en lugar de reinventar. - -## Elige un punto de partida - -| Si estás creando… | Bifurca esto | Por qué | -|---|---|---| -| Cualquier herramienta interna que registre "cosas" | `todo` | La demostración más pequeña y limpia de todos los primitivos | -| Cualquier cosa con cadenas de aprobación | `procurement` o `contracts` | Procesos de aprobación reales ya conectados | -| Cualquier cosa de cara al cliente con IA | `helpdesk` | Patrón de agente + copiloto de tickets | -| Un flujo de trabajo de un sector regulado | `compliance` | Auditoría + evidencias + mapeo de controles | -| Una aplicación de personas / organigrama | `hr` | Directorio + estructura jerárquica | - -## AI Builder + plantillas juntos - -Puedes bifurcar una plantilla y **aun así** usar el AI Builder sobre ella. -Instala `helpdesk` y luego di: - -> *"Añade un campo entero `csat_score` a `hd_ticket`, rango 1–5, pídelo al -> cerrar."* - -La IA amplía el paquete instalado en el mismo lugar. Sube el cambio al -repositorio de origen con `os package export`. - -## Adónde ir a continuación - -- [AI Builder](/docs/build/ai-builder) — amplía cualquier plantilla por chat -- [Packages](/docs/build/packages) — qué es realmente una plantilla -- [Marketplace](/docs/build/marketplace) — distribuye tu bifurcación -- [Quickstart](/docs/quickstart) — recorrido completo de extremo a extremo de la ruta del desarrollador diff --git a/content/docs/build/templates.fr.mdx b/content/docs/build/templates.fr.mdx deleted file mode 100644 index 3ccccc0..0000000 --- a/content/docs/build/templates.fr.mdx +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: Modèles -description: Packages de démarrage clonables — `todo`, `contracts`, `procurement`, `helpdesk`, et plus encore. -translation: - source_sha: 25ae072d41ab70627e03786cf2c69aa5a017f481c778b4d780c52201128f07e1 - guide_rev: 1 - mode: auto ---- - -Les modèles sont des **packages de démarrage clonables**. Chacun est une -véritable application structurée que vous pouvez installer depuis le -marketplace en un clic, ou cloner avec la CLI pour obtenir une base de -code TypeScript à étendre. - -Les modèles existent pour deux raisons : - -1. **Montrer plutôt que décrire** — une application multi-objets - fonctionnelle se lit plus vite que la documentation. -2. **Donner aux équipes d'ingénierie un point de départ** — lorsque vous - voulez du code sous contrôle de version, et pas seulement des - métadonnées générées par l'IA dans votre base de données. - -## Ce que contient le catalogue par défaut - -| Modèle | Domaine | Démarrage clonable pour… | -|---|---|---| -| **`todo`** | Tâches et projets | Tout outil de type « choses à faire, regroupées d'une manière ou d'une autre » | -| **`contracts`** | CLM avec extraction de clauses par IA | Approbations + IA documentaire | -| **`procurement`** | Fournisseurs, bons de commande, rapprochement à 3 voies | Chaînes d'approbation + réception | -| **`compliance`** | Contrôles SOC 2 / ISO 27001 | Flux de collecte de preuves | -| **`helpdesk`** | Support client orienté IA | Tickets + SLA + copilote IA | -| **`content`** | Calendrier éditorial + ROI par canal | Cycle de vie + métriques | -| **`hr`** | Annuaire, organigramme, congés | Applications centrées sur les personnes | -| **`project`** | Suivi de projets / tâches / jalons | Outils de gestion de projet | - -Source : [github.com/objectstack-ai/templates](https://github.com/objectstack-ai/templates). -Apache-2.0. Clonez sans demander. - -## Installer en 30 secondes (sans code) - -Dans Console : - -1. Ouvrez **Marketplace** → recherchez le modèle. -2. Cliquez sur **Install**. -3. Actualisez — la nouvelle application apparaît dans votre navigation. - -C'est fait. Enregistrements, vues, flows, permissions — tout est en ligne. - -## Cloner comme base de code (pour les ingénieurs) - -```bash -pnpm dlx @objectstack/cli create my-app --template todo -cd my-app -pnpm install -pnpm dev # http://localhost:4002 -``` - -Le clone est un package pnpm autonome — des fichiers `*.object.ts`, -`*.view.ts`, `*.flow.ts` que vous pouvez éditer, analyser, tester, -committer. Lorsque vous êtes satisfait : - -```bash -pnpm build -os package publish # → votre marketplace -``` - -Les clients qui installent votre fork obtiennent **votre** marque et -**vos** modifications. - -## Charte du modèle (le contrat social) - -Chaque modèle est livré avec un fichier `CHARTER.md` qui déclare sa -portée et ses limites strictes — généralement : ≤ 6 objets métier, -≤ 2 500 lignes de code sous `src/`, une application, une locale par -défaut. La charte existe pour que les modèles restent des **modèles**, -et non des produits à moitié finis. Si un fork dépasse ces limites, -publiez-le comme un nouveau modèle, ne surchargez pas un modèle existant. - -Consultez le [TEMPLATE_GUIDE.md](https://github.com/objectstack-ai/templates/blob/main/TEMPLATE_GUIDE.md) -en amont pour le protocole des suffixes de fichiers (`*.object.ts`, `*.state.ts`, `*.hook.ts`, …), -la séquence d'écriture (objects → state → hooks → views → flows → …), -et les services de plateforme polymorphes (`sys_comment`, `sys_attachment`, -`sys_audit_log`) que vous devriez réutiliser plutôt que de réinventer. - -## Choisir un point de départ - -| Si vous construisez… | Clonez ceci | Pourquoi | -|---|---|---| -| Tout outil interne qui suit des « choses » | `todo` | La démonstration la plus simple et la plus propre de toutes les primitives | -| Tout ce qui implique des chaînes d'approbation | `procurement` ou `contracts` | De véritables processus d'approbation déjà câblés | -| Tout ce qui est orienté client avec de l'IA | `helpdesk` | Modèle agent + copilote de ticket | -| Un flux de travail en secteur réglementé | `compliance` | Audit + preuves + cartographie des contrôles | -| Une application annuaire / organigramme | `hr` | Annuaire + structure hiérarchique | - -## AI Builder + modèles ensemble - -Vous pouvez cloner un modèle et **continuer** à utiliser l'AI Builder -par-dessus. Installez `helpdesk`, puis dites : - -> *« Ajoute un champ entier `csat_score` à `hd_ticket`, plage 1–5, -> demande-le à la clôture. »* - -L'IA étend le package installé sur place. Renvoyez la modification vers -le dépôt source avec `os package export`. - -## Pour aller plus loin - -- [AI Builder](/docs/build/ai-builder) — étendez n'importe quel modèle par chat -- [Packages](/docs/build/packages) — ce qu'est réellement un modèle -- [Marketplace](/docs/build/marketplace) — distribuez votre fork -- [Quickstart](/docs/quickstart) — le parcours développeur complet de bout en bout diff --git a/content/docs/build/templates.ja.mdx b/content/docs/build/templates.ja.mdx deleted file mode 100644 index 630b0dc..0000000 --- a/content/docs/build/templates.ja.mdx +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: テンプレート -description: フォーク可能なスターターパッケージ — `todo`、`contracts`、`procurement`、`helpdesk` など。 -translation: - source_sha: 25ae072d41ab70627e03786cf2c69aa5a017f481c778b4d780c52201128f07e1 - guide_rev: 1 - mode: auto ---- - -テンプレートは**フォーク可能なスターターパッケージ**です。それぞれが実際に -形になったアプリであり、marketplace からワンクリックでインストールするか、 -CLI でクローンして拡張可能な TypeScript コードベースを取得できます。 - -テンプレートが存在する理由は 2 つあります。 - -1. **語るより見せる** — 動作するマルチオブジェクトのアプリは、ドキュメントよりも - 素早く理解できます。 -2. **エンジニアリングチームに出発点を提供する** — DB に AI 生成のメタデータがある - だけでなく、ソース管理下にコードを置きたい場合に役立ちます。 - -## デフォルトカタログに含まれるもの - -| テンプレート | ドメイン | フォーク向けのスターター対象… | -|---|---|---| -| **`todo`** | タスクとプロジェクト | 「何らかの方法でグループ化された、やるべきこと」を扱うあらゆるツール | -| **`contracts`** | AI 条項抽出付きの CLM | 承認 + ドキュメント AI | -| **`procurement`** | ベンダー、発注書、3-way マッチ | 承認チェーン + 受領 | -| **`compliance`** | SOC 2 / ISO 27001 統制 | エビデンス収集ワークフロー | -| **`helpdesk`** | AI ファーストのカスタマーサポート | チケット + SLA + AI コパイロット | -| **`content`** | 編集カレンダー + チャネル ROI | ライフサイクル + メトリクス | -| **`hr`** | ディレクトリ、組織図、休暇 | 人材中心のアプリ | -| **`project`** | プロジェクト / タスク / マイルストーン追跡 | PM ツール | - -ソース: [github.com/objectstack-ai/templates](https://github.com/objectstack-ai/templates)。 -Apache-2.0。許可なくフォークしてください。 - -## 30 秒でインストール（コード不要） - -Console で: - -1. **Marketplace** を開く → テンプレートを検索する。 -2. **Install** をクリックする。 -3. 更新する — 新しいアプリがナビゲーションに表示されます。 - -完了です。レコード、ビュー、フロー、権限 — すべて稼働しています。 - -## コードベースとしてフォークする（エンジニア向け） - -```bash -pnpm dlx @objectstack/cli create my-app --template todo -cd my-app -pnpm install -pnpm dev # http://localhost:4002 -``` - -クローンは自己完結型の pnpm パッケージで、編集、lint、テスト、コミットが可能な -`*.object.ts`、`*.view.ts`、`*.flow.ts` ファイルで構成されています。準備が -できたら: - -```bash -pnpm build -os package publish # → your marketplace -``` - -あなたのフォークをインストールした顧客は、**あなたの**ブランドと**あなたの** -変更内容を受け取ります。 - -## テンプレート憲章（ソーシャルコントラクト） - -すべてのテンプレートは、そのスコープと厳格な制限を宣言する `CHARTER.md` を -備えています。典型的には、ビジネスオブジェクト 6 個以下、`src/` 配下のコード -2,500 行以下、アプリ 1 つ、デフォルトロケール 1 つです。憲章が存在するのは、 -テンプレートが未完成の製品ではなく、**テンプレート**であり続けるためです。 -フォークがこれらの制限を超えて成長した場合は、新しいテンプレートとして公開し、 -既存のものを肥大化させないでください。 - -ファイルサフィックスのプロトコル（`*.object.ts`、`*.state.ts`、`*.hook.ts` など）、 -オーサリングの順序（objects → state → hooks → views → flows → …）、および -再発明せずに再利用すべきポリモーフィックなプラットフォームサービス -（`sys_comment`、`sys_attachment`、`sys_audit_log`）については、上流の -[TEMPLATE_GUIDE.md](https://github.com/objectstack-ai/templates/blob/main/TEMPLATE_GUIDE.md) -を参照してください。 - -## 出発点を選ぶ - -| 構築するものが… | これをフォーク | 理由 | -|---|---|---| -| 「何か」を追跡する社内ツール全般 | `todo` | すべてのプリミティブを最小かつ最もクリーンに示すデモ | -| 承認チェーンを伴うもの | `procurement` または `contracts` | 実際の承認プロセスが組み込まれている | -| AI を備えた顧客向けのもの | `helpdesk` | エージェント + チケットコパイロットのパターン | -| 規制業界のワークフロー | `compliance` | 監査 + エビデンス + 統制マッピング | -| 人材 / 組織図アプリ | `hr` | ディレクトリ + レポートライン構造 | - -## AI Builder とテンプレートを組み合わせる - -テンプレートをフォークしても、その上で **引き続き** AI Builder を使用できます。 -`helpdesk` をインストールしてから、次のように指示します。 - -> *「`hd_ticket` に範囲 1〜5 の `csat_score` 整数フィールドを追加し、クローズ時に -> 入力を求めて。」* - -AI はインストール済みのパッケージをその場で拡張します。`os package export` で -変更をソースリポジトリにプッシュしてください。 - -## 次に進む先 - -- [AI Builder](/docs/build/ai-builder) — チャットで任意のテンプレートを拡張する -- [Packages](/docs/build/packages) — テンプレートとは実際には何か -- [Marketplace](/docs/build/marketplace) — あなたのフォークを配布する -- [Quickstart](/docs/quickstart) — 開発者パスのエンドツーエンド全体 diff --git a/content/docs/build/templates.ko.mdx b/content/docs/build/templates.ko.mdx deleted file mode 100644 index 2b4903a..0000000 --- a/content/docs/build/templates.ko.mdx +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: 템플릿 -description: 포크 가능한 스타터 패키지 — `todo`, `contracts`, `procurement`, `helpdesk` 등. -translation: - source_sha: 25ae072d41ab70627e03786cf2c69aa5a017f481c778b4d780c52201128f07e1 - guide_rev: 1 - mode: auto ---- - -템플릿은 **포크 가능한 스타터 패키지**입니다. 각 템플릿은 marketplace에서 -클릭 한 번으로 설치하거나, CLI로 클론하여 확장할 수 있는 TypeScript -코드베이스를 얻을 수 있는 실제로 형태를 갖춘 앱입니다. - -템플릿이 존재하는 두 가지 이유: - -1. **말보다 보여주기** — 동작하는 멀티 오브젝트 앱은 문서보다 더 빠르게 - 읽힙니다. -2. **엔지니어링 팀에 출발점 제공** — DB에 AI가 생성한 메타데이터만이 아니라, - 소스 관리 하에 있는 코드를 원할 때. - -## 기본 카탈로그에 포함되는 것 - -| 템플릿 | 도메인 | 포크 가능한 스타터 용도… | -|---|---|---| -| **`todo`** | 작업 및 프로젝트 | "어떤 식으로든 그룹화된 할 일" 도구 일체 | -| **`contracts`** | AI 조항 추출 기능이 있는 CLM | 승인 + 문서 AI | -| **`procurement`** | 공급업체, 발주서, 3-way 매칭 | 승인 체인 + 입고 | -| **`compliance`** | SOC 2 / ISO 27001 통제 | 증거 수집 워크플로우 | -| **`helpdesk`** | AI 우선 고객 지원 | 티켓 + SLA + AI 코파일럿 | -| **`content`** | 편집 일정 + 채널 ROI | 라이프사이클 + 지표 | -| **`hr`** | 디렉터리, 조직도, 휴가 | 인력 중심 앱 | -| **`project`** | 프로젝트 / 작업 / 마일스톤 추적 | PM 도구 | - -출처: [github.com/objectstack-ai/templates](https://github.com/objectstack-ai/templates). -Apache-2.0. 묻지 말고 포크하세요. - -## 30초 만에 설치 (코드 불필요) - -Console에서: - -1. **Marketplace**를 열고 → 템플릿을 검색합니다. -2. **Install**을 클릭합니다. -3. 새로고침하면 — 새 앱이 내비게이션에 나타납니다. - -완료. 레코드, 뷰, 플로우, 권한 — 모두 즉시 사용 가능합니다. - -## 코드베이스로 포크 (엔지니어용) - -```bash -pnpm dlx @objectstack/cli create my-app --template todo -cd my-app -pnpm install -pnpm dev # http://localhost:4002 -``` - -클론은 자체 완결적인 pnpm 패키지로 — `*.object.ts`, `*.view.ts`, -`*.flow.ts` 파일을 편집, 린트, 테스트, 커밋할 수 있습니다. 만족스러우면: - -```bash -pnpm build -os package publish # → your marketplace -``` - -여러분의 포크를 설치하는 고객은 **여러분의** 브랜드와 **여러분의** 수정 -사항을 받게 됩니다. - -## 템플릿 헌장 (사회적 계약) - -모든 템플릿은 범위와 엄격한 한계를 선언하는 `CHARTER.md`를 함께 제공합니다 — -일반적으로: 비즈니스 오브젝트 6개 이하, `src/` 하위 2,500 LOC 이하, 앱 1개, -기본 로케일 1개. 헌장은 템플릿이 절반만 완성된 제품이 아니라 **템플릿**으로 -유지되도록 하기 위해 존재합니다. 포크가 이러한 한계를 초과하면, 기존 템플릿을 -부풀리지 말고 새로운 템플릿으로 출시하세요. - -파일 접미사 프로토콜(`*.object.ts`, `*.state.ts`, `*.hook.ts`, …), -작성 순서(오브젝트 → 상태 → 훅 → 뷰 → 플로우 → …), 그리고 재발명하는 대신 -재사용해야 하는 다형성 플랫폼 서비스(`sys_comment`, `sys_attachment`, -`sys_audit_log`)에 대해서는 업스트림 -[TEMPLATE_GUIDE.md](https://github.com/objectstack-ai/templates/blob/main/TEMPLATE_GUIDE.md)를 -참고하세요. - -## 출발점 선택하기 - -| 만들고 있는 것이… | 이것을 포크하세요 | 이유 | -|---|---|---| -| "무언가"를 추적하는 내부 도구 일체 | `todo` | 모든 프리미티브를 가장 작고 깔끔하게 보여줌 | -| 승인 체인이 있는 무엇이든 | `procurement` 또는 `contracts` | 실제 승인 프로세스가 연결되어 있음 | -| AI가 포함된 고객 대면 무엇이든 | `helpdesk` | 에이전트 + 티켓 코파일럿 패턴 | -| 규제 산업 워크플로우 | `compliance` | 감사 + 증거 + 통제 매핑 | -| 인력 / 조직도 앱 | `hr` | 디렉터리 + 보고 구조 | - -## AI Builder + 템플릿 함께 사용하기 - -템플릿을 포크하고 **그 위에서** AI Builder를 **여전히** 사용할 수 있습니다. -`helpdesk`를 설치한 다음 이렇게 말하세요: - -> *"`hd_ticket`에 `csat_score` 정수 필드를 추가하고, 범위는 1–5, 마감 시 -> 입력하도록 요청해줘."* - -AI는 설치된 패키지를 그 자리에서 확장합니다. `os package export`로 변경 -사항을 소스 저장소에 푸시하세요. - -## 다음으로 갈 곳 - -- [AI Builder](/docs/build/ai-builder) — 채팅으로 모든 템플릿 확장 -- [Packages](/docs/build/packages) — 템플릿이 실제로 무엇인지 -- [Marketplace](/docs/build/marketplace) — 여러분의 포크 배포 -- [Quickstart](/docs/quickstart) — 개발자 경로의 전체 엔드투엔드 diff --git a/content/docs/build/templates.mdx b/content/docs/build/templates.mdx index 4b3b25d..02aee8b 100644 --- a/content/docs/build/templates.mdx +++ b/content/docs/build/templates.mdx @@ -44,13 +44,17 @@ Done. Records, views, flows, permissions — all live. ## Fork as a codebase (for engineers) ```bash -pnpm dlx @objectstack/cli create my-app --template todo +npm create objectstack@latest my-app cd my-app pnpm install -pnpm dev # http://localhost:4002 +pnpm dev ``` -The clone is a self-contained pnpm package — `*.object.ts`, +The scaffolder starts every project from its `blank` template. It no +longer fetches the content templates by name: on ObjectStack 17.7, +`--template todo` is refused as retired. + +The project is a self-contained pnpm package — `*.object.ts`, `*.view.ts`, `*.flow.ts` files you can edit, lint, test, commit. When you're happy: @@ -94,8 +98,9 @@ Install `helpdesk`, then say: > *"Add a `csat_score` integer field to `hd_ticket`, range 1–5, ask > for it on close."* -The AI extends the installed package in-place. Push the change up to -the source repo with `os package export`. +The AI extends the installed package in place. The change is live +metadata in your deployment, approved like any other AI Builder change; +it does not travel back to the template's source repository on its own. ## Where to go next diff --git a/content/docs/build/templates.zh-Hans.mdx b/content/docs/build/templates.zh-Hans.mdx deleted file mode 100644 index 818e14a..0000000 --- a/content/docs/build/templates.zh-Hans.mdx +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: 模板 -description: 可 fork 的起步包 —— `todo`、`contracts`、`procurement`、`helpdesk` 等等。 -translation: - source_sha: 25ae072d41ab70627e03786cf2c69aa5a017f481c778b4d780c52201128f07e1 - guide_rev: 1 - mode: auto ---- - -模板是**可 fork 的起步包**。每一个都是真实成型的应用，能从应用市场一键安装,也能用 CLI 克隆下来得到一个可扩展的 TypeScript 代码库。 - -模板存在的两个理由： - -1. **Show, don't tell** —— 一个能跑的多对象应用，比文档读得更快。 -2. **给工程团队一个起点** —— 当你想要代码在版本管理之下，而不只是 AI 在 DB 里生成的元数据。 - -## 默认目录里有什么 - -| 模板 | 领域 | 可 fork 用于… | -|---|---|---| -| **`todo`** | 任务与项目 | 任何"按某种方式分组的待办事项"工具 | -| **`contracts`** | 带 AI 条款抽取的 CLM | 审批 + 文档 AI | -| **`procurement`** | 供应商、PO、三方对账 | 审批链 + 收货 | -| **`compliance`** | SOC 2 / ISO 27001 控制 | 证据收集工作流 | -| **`helpdesk`** | AI 优先的客户支持 | 工单 + SLA + AI 副驾 | -| **`content`** | 编辑日历 + 渠道 ROI | 生命周期 + 指标 | -| **`hr`** | 通讯录、组织架构、休假 | 以人为中心的应用 | -| **`project`** | 项目 / 任务 / 里程碑跟踪 | PM 工具 | - -源码：[github.com/objectstack-ai/templates](https://github.com/objectstack-ai/templates)。Apache-2.0。Fork 无需打招呼。 - -## 30 秒安装（零代码） - -在 Console 里： - -1. 打开 **Marketplace**，搜索模板。 -2. 点击 **Install**。 -3. 刷新 —— 新应用出现在你的导航里。 - -完成。记录、视图、流程、权限 —— 全活了。 - -## 作为代码库 Fork（面向工程师） - -```bash -pnpm dlx @objectstack/cli create my-app --template todo -cd my-app -pnpm install -pnpm dev # http://localhost:4002 -``` - -克隆下来是一个自包含的 pnpm 包 —— `*.object.ts`、`*.view.ts`、`*.flow.ts` 文件，你可以编辑、lint、测试、提交。满意之后： - -```bash -pnpm build -os package publish # → 你的应用市场 -``` - -安装你 fork 的客户拿到**你的**品牌和**你的**修改。 - -## 模板章程（社会契约） - -每个模板都附带 `CHARTER.md`，声明其范围和硬性限制 —— 通常是：≤ 6 个业务对象、`src/` 下 ≤ 2,500 LOC、一个 app、一个默认 locale。章程的存在是为了让模板保持**模板**身份，而不是半成品。如果 fork 超过这些限制，请作为新模板发布，不要把已有的撑大。 - -文件后缀协议（`*.object.ts`、`*.state.ts`、`*.hook.ts`……）、编写顺序（对象 → 状态 → Hook → 视图 → 流程 → ……），以及你应该复用而非重造的多态平台服务（`sys_comment`、`sys_attachment`、`sys_audit_log`），见上游 [TEMPLATE_GUIDE.md](https://github.com/objectstack-ai/templates/blob/main/TEMPLATE_GUIDE.md)。 - -## 怎么选起点 - -| 如果你在做… | Fork 这个 | 为什么 | -|---|---|---| -| 任何跟踪"东西"的内部工具 | `todo` | 最小、最干净地演示所有原语 | -| 任何带审批链的东西 | `procurement` 或 `contracts` | 真实的审批流程已经接好 | -| 任何带 AI 的客户向应用 | `helpdesk` | Agent + 工单副驾模式 | -| 受监管行业的工作流 | `compliance` | 审计 + 证据 + 控制项映射 | -| 人员 / 组织架构应用 | `hr` | 通讯录 + 汇报关系 | - -## AI Builder + 模板 一起用 - -你可以 fork 一个模板，**继续**在上面用 AI Builder。安装 `helpdesk`，然后说： - -> *"在 `hd_ticket` 加一个 `csat_score` 整数字段，1–5 范围，关闭时询问。"* - -AI 就地扩展已安装的包。用 `os package export` 把变更推回源码仓库。 - -## 下一步 - -- [AI Builder](/docs/build/ai-builder) —— 用对话扩展任何模板 -- [Packages](/docs/build/packages) —— 模板实际是什么 -- [Marketplace](/docs/build/marketplace) —— 分发你的 fork -- [Quickstart](/docs/quickstart) —— 开发者路径端到端 diff --git a/content/docs/build/templates.zh-Hant.mdx b/content/docs/build/templates.zh-Hant.mdx deleted file mode 100644 index 1f4e838..0000000 --- a/content/docs/build/templates.zh-Hant.mdx +++ /dev/null @@ -1,90 +0,0 @@ ---- -# @generated zh-Hant from zh-Hans -- do not edit. Edit the English source, then regenerate: pnpm --filter @objectos/docs gen:zh-hant -title: 模板 -description: 可 fork 的起步包 —— `todo`、`contracts`、`procurement`、`helpdesk` 等等。 -translation: - source_sha: 25ae072d41ab70627e03786cf2c69aa5a017f481c778b4d780c52201128f07e1 - guide_rev: 1 - mode: auto ---- - -模板是**可 fork 的起步包**。每一個都是真實成型的應用，能從應用市場一鍵安裝,也能用 CLI 克隆下來得到一個可擴充套件的 TypeScript 程式碼庫。 - -模板存在的兩個理由： - -1. **Show, don't tell** —— 一個能跑的多物件應用，比文件讀得更快。 -2. **給工程團隊一個起點** —— 當你想要程式碼在版本管理之下，而不只是 AI 在 DB 裡生成的後設資料。 - -## 預設目錄裡有什麼 - -| 模板 | 領域 | 可 fork 用於… | -|---|---|---| -| **`todo`** | 任務與專案 | 任何"按某種方式分組的待辦事項"工具 | -| **`contracts`** | 帶 AI 條款抽取的 CLM | 審批 + 文件 AI | -| **`procurement`** | 供應商、PO、三方對賬 | 審批鏈 + 收貨 | -| **`compliance`** | SOC 2 / ISO 27001 控制 | 證據收集工作流 | -| **`helpdesk`** | AI 優先的客戶支援 | 工單 + SLA + AI 副駕 | -| **`content`** | 編輯日曆 + 渠道 ROI | 生命週期 + 指標 | -| **`hr`** | 通訊錄、組織架構、休假 | 以人為中心的應用 | -| **`project`** | 專案 / 任務 / 里程碑跟蹤 | PM 工具 | - -原始碼：[github.com/objectstack-ai/templates](https://github.com/objectstack-ai/templates)。Apache-2.0。Fork 無需打招呼。 - -## 30 秒安裝（零程式碼） - -在 Console 裡： - -1. 開啟 **Marketplace**，搜尋模板。 -2. 點選 **Install**。 -3. 重新整理 —— 新應用出現在你的導航裡。 - -完成。記錄、檢視、流程、許可權 —— 全活了。 - -## 作為程式碼庫 Fork（面向工程師） - -```bash -pnpm dlx @objectstack/cli create my-app --template todo -cd my-app -pnpm install -pnpm dev # http://localhost:4002 -``` - -克隆下來是一個自包含的 pnpm 包 —— `*.object.ts`、`*.view.ts`、`*.flow.ts` 檔案，你可以編輯、lint、測試、提交。滿意之後： - -```bash -pnpm build -os package publish # → 你的应用市场 -``` - -安裝你 fork 的客戶拿到**你的**品牌和**你的**修改。 - -## 模板章程（社會契約） - -每個模板都附帶 `CHARTER.md`，宣告其範圍和硬性限制 —— 通常是：≤ 6 個業務物件、`src/` 下 ≤ 2,500 LOC、一個 app、一個預設 locale。章程的存在是為了讓模板保持**模板**身份，而不是半成品。如果 fork 超過這些限制，請作為新模板釋出，不要把已有的撐大。 - -檔案字尾協議（`*.object.ts`、`*.state.ts`、`*.hook.ts`……）、編寫順序（物件 → 狀態 → Hook → 檢視 → 流程 → ……），以及你應該複用而非重造的多型平臺服務（`sys_comment`、`sys_attachment`、`sys_audit_log`），見上游 [TEMPLATE_GUIDE.md](https://github.com/objectstack-ai/templates/blob/main/TEMPLATE_GUIDE.md)。 - -## 怎麼選起點 - -| 如果你在做… | Fork 這個 | 為什麼 | -|---|---|---| -| 任何跟蹤"東西"的內部工具 | `todo` | 最小、最乾淨地演示所有原語 | -| 任何帶審批鏈的東西 | `procurement` 或 `contracts` | 真實的審批流程已經接好 | -| 任何帶 AI 的客戶嚮應用 | `helpdesk` | Agent + 工單副駕模式 | -| 受監管行業的工作流 | `compliance` | 審計 + 證據 + 控制項對映 | -| 人員 / 組織架構應用 | `hr` | 通訊錄 + 彙報關係 | - -## AI Builder + 模板 一起用 - -你可以 fork 一個模板，**繼續**在上面用 AI Builder。安裝 `helpdesk`，然後說： - -> *"在 `hd_ticket` 加一個 `csat_score` 整數字段，1–5 範圍，關閉時詢問。"* - -AI 就地擴充套件已安裝的包。用 `os package export` 把變更推回原始碼倉庫。 - -## 下一步 - -- [AI Builder](/docs/build/ai-builder) —— 用對話擴充套件任何模板 -- [Packages](/docs/build/packages) —— 模板實際是什麼 -- [Marketplace](/docs/build/marketplace) —— 分發你的 fork -- [Quickstart](/docs/quickstart) —— 開發者路徑端到端 diff --git a/content/docs/configure/data-sources.mdx b/content/docs/configure/data-sources.mdx index 1d135d1..e87d86c 100644 --- a/content/docs/configure/data-sources.mdx +++ b/content/docs/configure/data-sources.mdx @@ -29,18 +29,22 @@ core fields: | `driver` | Which driver handles the connection (`postgres`, `mysql`, `sqlite`, `mongodb`, `memory`, or a plugin-contributed driver) | | `config` | Driver-specific connection settings (host, database, credentials, …) | | `pool` | Connection-pool sizing (`min`, `max`, timeouts) | -| `readReplicas` | Optional read-only replica configs | -| `capabilities` | Override what the driver advertises it can push down | -| `healthCheck` | Liveness probe interval/timeout | +| `schemaMode` | Who owns the schema: `managed` (the default) lets ObjectOS create and alter tables; `external` or `validate-only` declares a database ObjectOS does not own, where it runs no DDL | +| `external` | The federation policy of an external datasource — its write gate and boot validation — plus `credentialsRef`, the secrets-store reference any datasource may carry | | `active` | Whether the connection is enabled | +`readReplicas`, `capabilities` (with its `readOnly` flag), `healthCheck` +and `retryPolicy` were removed in ObjectStack 17.0: no runtime path read +any of them. The parse refuses each one, naming the mechanism that does +decide the behaviour. + The shipped drivers are: | Driver package | `driver` | Backends | |---|---|---| | `@objectstack/driver-sql` | `postgres`, `mysql`, `sqlite` | PostgreSQL, MySQL, SQLite (via knex) | | `@objectstack/driver-mongodb` | `mongodb` | MongoDB | -| `@objectstack/driver-memory` | `memory` | In-process (tests, demos) | +| `@objectstack/driver-memory` | `memory` | In-process, for tests — not a boot store since ObjectStack 17.7 | | `@objectstack/driver-sqlite-wasm` | `sqlite` (WASM) | SQLite in WebContainers / browser | ## Declaring datasources @@ -53,19 +57,25 @@ Define each connection with `defineDatasource()`, then list them under // src/datasources/business.datasource.ts import { defineDatasource } from '@objectstack/spec'; -// Connect to an EXISTING production database. The password is never inline: -// it lives in the secrets store, and the datasource only references it. +// Connect to an EXISTING production database that ObjectOS does not own. +// `external` mode: ObjectOS runs no DDL here, and writes stay off until you +// opt in. The password is never inline: it lives in the secrets store, and +// the datasource only references it. export const BusinessDb = defineDatasource({ name: 'business_primary', label: 'Business System (Postgres)', driver: 'postgres', + schemaMode: 'external', config: { host: 'db.internal.example.com', port: 5432, database: 'business', - username: 'objectos', + username: 'objectos_readonly', // a database user granted SELECT only + }, + external: { + allowWrites: false, // the default: the datasource refuses writes + credentialsRef: 'secret:business_db/password', }, - external: { credentialsRef: 'secret:business_db/password' }, pool: { min: 1, max: 10 }, active: true, }); @@ -117,7 +127,9 @@ import { ObjectSchema, Field } from '@objectstack/spec/data'; export const Customer = ObjectSchema.create({ name: 'biz_customer', label: 'Customer', - datasource: 'business_primary', // ← reads/writes go to the business DB + sharingModel: 'private', + datasource: 'business_primary', // ← queries go to the business DB + external: { remoteName: 'customers' }, // the remote TABLE name fields: { name: Field.text({ label: 'Name', required: true }), email: Field.text({ label: 'Email' }), @@ -157,6 +169,7 @@ export const AnalyticsReplica = defineDatasource({ name: 'analytics_replica', label: 'Analytics replica', driver: 'postgres', + schemaMode: 'external', config: { host: 'replica.internal.example.com', port: 5432, @@ -171,7 +184,7 @@ export default defineStack({ datasourceMapping: [ { namespace: 'biz', datasource: 'business_primary' }, { objectPattern: 'report_*', datasource: 'analytics_replica' }, - { package: 'com.example.logs', datasource: 'business_primary' }, + { package: 'com.example.logs', datasource: 'default' }, { default: true, datasource: 'default' }, ], }); @@ -201,38 +214,33 @@ flow: generate one `ObjectSchema.create` file per table, mapping SQL columns to `Field.*` types and foreign keys to `Field.lookup(...)`. Set each object's `datasource` to your connection (or rely on - `datasourceMapping`). + `datasourceMapping`), and `external.remoteName` where the table name + differs from the object name. 3. **Review & refine** the generated objects — add labels, field groups, validations, and permissions. The output is ordinary source you own and commit, just like `hotcrm/src/objects/*.object.ts`. -4. **Run.** The objects now read and write your existing tables through - the bound datasource. +4. **Run.** The objects now read your existing tables through the bound + datasource. At boot the runtime checks each one against its table + (`external.validation`), and by default a mismatch fails the boot. + Writes stay off until both gates + open: `external.allowWrites: true` on the datasource **and** + `external.writable: true` on the object. Because the generated objects are plain source, you get full control: keep what fits, drop columns you don't want to expose, and layer ObjectOS features (history tracking, activities, sharing rules) on top of a database the platform never had to own. -## Capability-aware query pushdown +## Query pushdown -Each datasource advertises `DatasourceCapabilities` — whether it can -handle filters, sorting, pagination, aggregations, joins, full-text -search, transactions, and more. ObjectQL uses this to decide what to -**push down** to the database versus what to evaluate in memory: +What runs in the database and what the engine evaluates is decided by +each driver itself, not by datasource metadata. A filter on a federated +object, such as `?tier=premium`, is pushed down to the remote query. -| Capability | Effect when supported | -|---|---| -| `queryFilters` | `WHERE` clauses run in the database | -| `querySorting` / `queryPagination` | `ORDER BY` / `LIMIT` run server-side | -| `queryAggregations` | `GROUP BY` / aggregates run server-side | -| `joins` | Related-object joins run server-side | -| `fullTextSearch` | Search hits a native index | -| `readOnly` | The connection rejects writes | - -A capable SQL datasource pushes nearly everything down; a limited or -read-only source gets the same query results, just with more work done in -the engine. You can override the advertised set per datasource via the -`capabilities` field when you know better than the driver default. +There is no `capabilities` block to tune. It was removed in ObjectStack +17.0 because nothing read it: declaring a capability never changed which +path ran, and its `readOnly` flag never stopped a write. For read-only +access, see [Security notes](#security-notes). ## AI over connected data @@ -257,22 +265,27 @@ configuration that backs the `default` datasource. ## Security notes -- **Never inline credentials.** Pull host/user/password from environment - variables (or a secrets manager) as shown above. -- **Use read-only connections** for systems you don't intend to write to - — set the source `readOnly` capability (or a read-only DB user) so a - stray write can't reach production. +- **Never inline credentials.** Put the password in the secrets store and + reference it with `external.credentialsRef`, as shown above. +- **Use a read-only database user** for systems you don't intend to write + to — grant it `SELECT` only. Then nothing that reaches the database + through that connection can write, inside ObjectOS or not. On an + external datasource, `external.allowWrites: false` — the default — also + refuses writes in ObjectOS's own query path. There is no `readOnly` key: + the one that existed never gated a write, and ObjectStack 17.0 removed + it. - **Scope with permissions.** Object- and field-level permissions apply to connected data exactly as they do to native objects. ## In-product external datasource federation The flow above — connect a database, model objects, generate them with a -coding agent — is the general path. The **turn-key federation** flow on top -of it, specified in +coding agent — runs on **turn-key federation**: `schemaMode: 'external'`, +specified in [ADR-0015](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0015-external-datasource-federation.md) (status: *Accepted*), **ships today**: bind objects to tables ObjectOS does -not own, with validation gates around them. +not own, with validation gates around them. It is read-only by default and +early: expect the read path to be the mature one. It is documented once, with the framework docs that own the surface — [External Datasources (Federation)](https://docs.objectstack.ai/docs/data-modeling/external-datasources). diff --git a/content/docs/extend-existing-systems.mdx b/content/docs/extend-existing-systems.mdx index 9142417..f499846 100644 --- a/content/docs/extend-existing-systems.mdx +++ b/content/docs/extend-existing-systems.mdx @@ -25,9 +25,11 @@ model as everything else. The system of record stays the system of record. You don't replace your business system. You put ObjectOS *next to* it and point it at the same database: -1. **Connect** the existing database as a [datasource](/docs/configure/data-sources). - Credentials come from your environment. Start read-only — a `readOnly` - datasource, or a read-only database user — and enable writes +1. **Connect** the existing database as an external + [datasource](/docs/configure/data-sources) (`schemaMode: 'external'`): + ObjectOS runs no DDL against it, and writes stay off until you opt in. + The password lives in the secrets store, never in the datasource. Connect + with a database user that can only read, and enable writes deliberately. 2. **Model** the tables as objects — by hand, or by letting a coding agent scan the schema and generate source-level object files for you. @@ -45,7 +47,7 @@ are, and the legacy application keeps writing them. | Concern | How ObjectOS handles it | |---|---| | "We can't move the data" | The data never moves. ObjectOS connects to your database in place. | -| "We can't risk writes to production" | Start read-only — the `readOnly` capability, or a read-only database user — and enable writes deliberately, per object, once you trust the model. | +| "We can't risk writes to production" | Federation is read-only by default: a write needs an opt-in on the datasource (`external.allowWrites: true`) **and** on each object (`external.writable: true`). A database user granted `SELECT` only holds on every path, inside ObjectOS or not. | | "Modeling every table is weeks of work" | A coding agent scans the schema and generates one object file per table — you review and refine, you don't hand-type. | | "AI can't be trusted with our data" | Agents run as the **signed-in user** and obey object-, record-, and field-level permissions. They never see more than the person behind them. | | "Our data can't leave our network" | On ObjectOS Enterprise, ObjectOS runs in your environment: business data and prompts stay inside your perimeter. | diff --git a/content/docs/index.mdx b/content/docs/index.mdx index 127a92e..6b3787a 100644 --- a/content/docs/index.mdx +++ b/content/docs/index.mdx @@ -38,7 +38,9 @@ construction. Either ObjectOS edition then takes you to the same place — sign in, and: - **Talk to the AI Builder** — *"I need to track support tickets with - priority and assignee"* — and watch the metadata get generated. See + priority and assignee"* — and watch it write your + [ontology](/docs/ontology), the object and its fields, as a small + diff you approve. See [Build → AI Builder](/docs/build/ai-builder). - **Install a template** from the built-in marketplace (Todo, Contracts, Helpdesk, …) and have a real app in one click. @@ -52,7 +54,7 @@ Either ObjectOS edition then takes you to the same place — sign in, and: |---|---|---| | **Retool / Appsmith** | UI builder is great, but your data sits in their cloud and their pricing scales with users | Hosted (ObjectOS Cloud) or inside your network (ObjectOS Enterprise); built on open-source ObjectStack (Apache-2.0), so the ontology is yours to export; no seat tax — AI seats only | | **Supabase / Firebase** | Backend-as-a-service is fast but vendor-locked; multi-tenant SaaS by design | Same DX (auto APIs, auth, storage), but the definition is yours: export it and run it on the open ObjectStack runtime, or run ObjectOS Enterprise on your own database | -| **Salesforce / NetSuite** | Powerful platform, painful customization, eye-watering per-seat cost | Same metadata-driven model (objects, fields, roles, sharing rules), hosted or self-managed, no seat tax — viewers and non-AI users are free | +| **Salesforce / NetSuite** | Powerful platform, painful customization, eye-watering per-seat cost | A familiar vocabulary (objects, fields, permission sets, sharing rules), but the definition is an open ontology that AI writes, agents operate, and you can export to the Apache-2.0 runtime; hosted or self-managed, no seat tax — viewers and non-AI users are free | | **Rolling your own (Next + Prisma + NextAuth)** | You rebuild RBAC, audit, file uploads, settings, webhooks, jobs every time | Ship the actual business logic; the platform plumbing is already there | ## What you get out of the box @@ -62,6 +64,7 @@ Either ObjectOS edition then takes you to the same place — sign in, and: | **Auto REST API** | Every object you declare gets `/api/v1/data/` with filter/sort/paginate | | **The UI** (`/_console/`) | Generated screens: browse and edit records, and **Setup** to manage users/roles/permission sets, view audit log, sessions, API keys, settings | | **Account** ([inside the UI](/docs/resources/glossary#surface)) | Login, register, password reset, OAuth, OIDC/SSO, passkeys, 2FA | +| **MCP server** (`/api/v1/mcp`) | On by default: every object is a tool, and so is every action you expose to AI; an agent connects as a user, under that user's permissions — see [Connect AI Tools (MCP)](/docs/configure/mcp) | | **20+ plugins** | RBAC + row-level security, audit, file storage, queues, jobs, email, AI, webhooks — declarative, on demand | ## What stays yours @@ -80,7 +83,7 @@ first-class Enterprise deployment target — see ## Find your docs -This documentation serves three audiences — start at the section that +This documentation serves four audiences — start at the section that matches how you use ObjectOS: | You are … | You want to … | Start here | @@ -88,6 +91,7 @@ matches how you use ObjectOS: | **An everyday user** | Work in the apps: records, views, dashboards, approvals | [Use](/docs/use) | | **A builder** | Create apps: data models, interfaces, automation, AI agents | [Build](/docs/build) | | **An administrator** | Run the platform: users, permissions, settings, deployment | [Configure](/docs/configure), [Deploy](/docs/deploy), [Operate](/docs/operate/production) | +| **An agent, or whoever connects one** | Operate the app over MCP — read and write records, run the actions exposed to AI — under a user's permissions | [Connect AI Tools (MCP)](/docs/configure/mcp) | ## Where to go next diff --git a/content/docs/meta.json b/content/docs/meta.json index c00e70b..34d6776 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -3,6 +3,7 @@ "pages": [ "index", "why", + "ontology", "extend-existing-systems", "quickstart", "architecture", diff --git a/content/docs/ontology.mdx b/content/docs/ontology.mdx new file mode 100644 index 0000000..5a34dce --- /dev/null +++ b/content/docs/ontology.mdx @@ -0,0 +1,80 @@ +--- +title: Your ontology in ObjectOS +seoTitle: "Your Ontology in ObjectOS: Core, Projections, Where It Lives" +description: What your ontology is on ObjectOS — the core the runtime runs, the projections authored beside it, where it lives, and what it is not. +--- + +**The ontology is the software.** On ObjectOS, *your ontology* is the +definition of your business that the runtime executes: one typed, +versioned body of ObjectStack metadata. The runtime derives the database +schema, the REST API, the Console and the MCP tools from it, and enforces +it on every call. This page maps the word onto this site; the full account +is [Business Ontology](https://objectstack.ai/docs/concepts/ontology) in the +ObjectStack docs. + +## The core + +Six kinds of thing make up the ontology itself: + +| Core | What it declares | On this site | +|---|---|---| +| **Objects and fields** | The entities of the business and their typed attributes | [Data Model](/docs/build/data), [Field Types](/docs/reference/field-types) | +| **Relations** | Lookups and master-detail links between objects | [Relationships](/docs/build/data/relationships) | +| **Actions** | The operations a user — or, once its author exposes it, an agent — may invoke on a record | [Actions](/docs/build/interface/actions) | +| **Permissions** | Who may read, create, edit and delete what: permission sets, record access, field-level security | [Permissions](/docs/configure/permissions) | +| **Flows** | The business processes: flows, record triggers, schedules, approvals, workflows | [Automation](/docs/build/automation) | +| **Agent and tool definitions** | The AI agents the app ships with, their skills, and the tools they may call | [Agents](/docs/build/agents) | + +## The projections + +Views, dashboards, apps and translations are authored as metadata too, and +they pass the same validation gate, but they are **projections** of the +ontology, not part of it. Change the core and they follow; remove one and +the business it showed is unchanged. + +| Projection | What it projects | On this site | +|---|---|---| +| **Views** | An object's fields and permissions onto a list, form, kanban or calendar | [Views](/docs/build/interface/views), [Forms](/docs/build/interface/forms) | +| **Dashboards** | Queries over objects onto charts | [Dashboards](/docs/build/interface/dashboards) | +| **Apps** | Objects, views and actions, grouped into a navigable product | [Apps](/docs/build/interface/apps) | +| **Translations** | Every label, into a locale | [Localization](/docs/configure/localization) | + +## Where it lives on ObjectOS + +One definition, in three forms: + +| Form | What it is | +|---|---| +| **Tenant metadata** | What the [AI Builder](/docs/build/ai-builder) and Studio write: live metadata in your deployment. An AI Builder change queues for a person's approval before it applies | +| **Repository source** | What your developers and their coding agent write, with the [AI skills](/docs/build/ai-skills): `objectstack.config.ts` and its metadata files, reviewed as pull requests | +| **Compiled artifact** | What `os compile` produces: `objectstack.json`, which a deployment boots — see [Boot modes](/docs/architecture#boot-modes). Keep every published one ([Backup](/docs/operate/backup)) | + +Whichever form you author in, the metadata passes the same +[validation gate](/docs/resources/glossary#validation-gate) before it runs. +On either edition the ontology is yours: it is ordinary ObjectStack +metadata, and you can export it and run it on the open-source ObjectStack +runtime. + +## What it is not + +- **Not a knowledge ontology.** There is no class inheritance, no axioms + and no reasoner. The definition is validated, then run. +- **Not a semantic layer over your existing systems.** A semantic layer + describes a business it does not run. Your ontology is the system: the + database, API, UI and agent tools are derived from it. Connecting a + database you already run is possible, read-only by default and early — + see [Extend Existing Systems](/docs/extend-existing-systems). + +## Read further + +This site documents the runtime; the ObjectStack site owns the concept: + +- [Business Ontology](https://objectstack.ai/docs/concepts/ontology) — what + the word means, and how the runtime executes it +- [How ObjectStack compares](https://objectstack.ai/docs/concepts/compare) — + beside knowledge ontologies, semantic layers, metadata platforms and AI + code generation +- [When to use ObjectStack](https://objectstack.ai/docs/concepts/when-to-use) + — where it fits today, and where it does not +- [The Ontology Is the Software](https://objectstack.ai/blog/the-ontology-is-the-software) + — the long form diff --git a/content/docs/resources/faq.mdx b/content/docs/resources/faq.mdx index 025333f..2de565f 100644 --- a/content/docs/resources/faq.mdx +++ b/content/docs/resources/faq.mdx @@ -32,6 +32,29 @@ is self-managed and needs no cloud service to run — connecting it to a control plane is optional. The open-source ObjectStack runtime needs no account at all. +## The ontology + +### What does ObjectOS mean by ontology? + +Your app's definition: its objects and fields, relations, actions, +permissions, flows, and agent and tool definitions, as one typed, +versioned body of ObjectStack metadata that the runtime runs. Views, +dashboards, apps and translations are projections of it, not part of it. +It is executable — validated, then run — not a knowledge ontology with +inheritance, axioms and a reasoner. See +[Your ontology in ObjectOS](/docs/ontology). + +### Is ObjectOS a semantic layer? + +No. A semantic layer maps systems that already exist so they can be +queried; it describes a business but does not run it. ObjectOS runs your +ontology: the database, REST API, UI and agent tools are derived from it. +You can connect a database you already run as an external datasource — +read-only by default, and early — and that system of record stays where +it is. See [Extend Existing Systems](/docs/extend-existing-systems), and +[How ObjectStack compares](https://objectstack.ai/docs/concepts/compare) +for the side-by-side. + ## Architecture ### Can I use Postgres / MySQL / MongoDB? @@ -151,11 +174,14 @@ Native connectors for popular iPaaS tools are on the roadmap. ### Can AI agents call my ObjectOS? -Yes, via MCP (`@objectstack/mcp`) — exposes objects (and, increasingly, -actions) as MCP tools that Claude Desktop, IDEs, Claude Code, or any other MCP -client can use. This is the **AI path on the free, open-source ObjectStack -framework** (bring your own model); the in-product AI Builder / "ask your data" -assistant is what the paid ObjectOS editions add. See [AI Service](/docs/configure/ai). +Yes. Every ObjectOS deployment is an MCP server at `/api/v1/mcp`, on by +default: every object is a tool, and so is every action its author +exposed to AI (`ai.exposed`). Claude Code, Claude Desktop, IDEs or any +other MCP client connect as a user, and every call runs as that user, +under the same permissions and audit as a person. The open-source +ObjectStack runtime serves the same MCP surface, with your own model; +ObjectOS adds the in-product AI — the AI Builder and the assistants your +users chat with. See [Connect AI Tools (MCP)](/docs/configure/mcp). ## Customization diff --git a/content/docs/resources/glossary.mdx b/content/docs/resources/glossary.mdx index e217952..fb8d780 100644 --- a/content/docs/resources/glossary.mdx +++ b/content/docs/resources/glossary.mdx @@ -9,8 +9,10 @@ A single canonical definition for each term used in this documentation. ### Action A named operation declared in metadata, invocable via REST -(`/api/v1/data//actions/`), buttons in the UI, or flow -steps. Inherits the caller's permissions. +(`/api/v1/actions//`), buttons in the UI, and — once its +author exposes it to AI (`ai.exposed`) — agents. Whether the caller may +invoke it is checked as the caller; a `script` body then runs as trusted +app code. See [Actions](/docs/build/interface/actions). ### Adapter @@ -51,9 +53,14 @@ permissions, flows, and agent and tool definitions — as one executable, versioned whole: authored as typed ObjectStack metadata, validated rather than reasoned over, and run by the runtime, which derives the database, REST API, UI and MCP tools from it. Views, dashboards, apps and -translations are projections of it, not part of it. It is yours on either -ObjectOS edition: export it and run it on the open-source ObjectStack -runtime. The full account is +translations are [projections](#projection) of it, not part of it. + +It is executable, not a knowledge ontology: no object inheritance, no +axioms, no reasoner. Nor is it a semantic layer — a read-only mapping over +existing systems that describes a business but does not run it. It is +yours on either ObjectOS edition: export it and run it on the open-source +ObjectStack runtime. On this site, see +[Your ontology in ObjectOS](/docs/ontology); the full account is [Business Ontology](https://objectstack.ai/docs/concepts/ontology) in the ObjectStack docs. @@ -144,9 +151,11 @@ package registry. See [Marketplace](/docs/build/marketplace). ### MCP (Model Context Protocol) -An open protocol for AI agents to discover and call tools. -ObjectOS can expose its objects + actions as MCP via -`@objectstack/mcp`. +An open protocol for AI agents to discover and call tools. Every +ObjectOS deployment is an MCP server at `/api/v1/mcp`, on by default: +each object is a tool, and so is each action its author exposed to AI +(`ai.exposed`). Every call runs as the caller. See +[Connect AI Tools (MCP)](/docs/configure/mcp). ### Object @@ -210,6 +219,16 @@ Old name for **Environment**. It survives in inherited configuration and in framework-internal identifiers; ObjectOS documentation says *Environment*. +### Projection + +A view, dashboard, app or translation: metadata authored beside the +[business ontology](#business-ontology) and checked by the same +[validation gate](#validation-gate), but not part of the ontology. A +projection presents the core — an object's fields on a grid, queries over +objects on a chart, every label in a locale. Change the core and its +projections follow; remove a projection and the business it showed is +unchanged. See [Your ontology in ObjectOS](/docs/ontology#the-projections). + ### Record Share A direct grant of access to a specific record for one recipient — a @@ -284,6 +303,18 @@ deployments](/docs/reference/environment-variables#multi-organization-deployment The condition that fires a flow — record event (`after_insert`), schedule (cron), or manual invocation. +### Validation gate + +The one set of checks all metadata passes before it runs: the +`@objectstack/spec` schemas, and the authoring rules that catch what +type-checks but would fail silently at runtime — a bad CEL predicate, a +reference to something that does not exist. `os validate` and +`os compile` run it on repository source, and the runtime applies the +same gate to every metadata write that goes live, from the AI Builder, +Studio or the metadata API. See +[Validating Metadata](https://objectstack.ai/docs/deployment/validating-metadata) +in the ObjectStack docs. + ### View A declarative UI configuration — list, form, kanban, calendar, gantt — diff --git a/content/docs/why.mdx b/content/docs/why.mdx index 10d3602..acad4c8 100644 --- a/content/docs/why.mdx +++ b/content/docs/why.mdx @@ -57,10 +57,29 @@ Common scenarios where it's a fit: | Standing up an internal admin for a SaaS product | One Node process, slots in next to your existing services — or a Cloud tenant with nothing to run | | Air-gapped or on-prem deployment for an enterprise customer | A first-class ObjectOS Enterprise target: air-gapped licenses validate offline, and the AI service can point at a local model | | Multi-tenant internal portal (several organizations, one deployment) | A walled tenancy posture puts up the per-organization isolation wall, enforced inside the runtime — an Enterprise capability, see [License & Pricing](/docs/resources/license). It separates the organizations' data and memberships, not their schema: they share one database and one metadata set | -| You want your users to "vibe-code" their own extensions safely | The AI Builder + HITL approval queue + audit log are the whole point | +| You want your users to extend their apps by describing the change, safely | The AI Builder + HITL approval queue + audit log are the whole point | +| The long tail of departmental apps around a core ERP — vendor onboarding, inspections, internal requests | Each one is a small, typed definition that changes often, instead of a spreadsheet that gets emailed around | +| A back office that agents operate from day one | Every deployment is an MCP server, on by default; agents act through the same permissions and audit as people | ## Don't use ObjectOS if you … +- need to replace the core ERP or finance system of a large enterprise + → a general ledger, consolidation, tax and payroll carry regulation + that packaged systems already encode. Build around that core, not + instead of it. +- get your value mostly from integrating many existing systems → + connecting a database you already run is + [read-only by default and early](/docs/extend-existing-systems); a + layer over those systems fits better. +- need analytics over a data lake → dashboards run over the app's own + objects; they are not built to query a lake. +- work in an algorithm-heavy domain, such as pricing or scheduling → + the ontology declares what can be done, not an optimiser. Wrap the + algorithm as an [action](/docs/build/interface/actions) and permissions, + audit and agent access apply to it like any other. +- must run on a platform that is itself certified → ObjectOS is not; + certification is of a running deployment, and certifying yours is work + you own — see [Security & Compliance](/docs/reference/security#compliance-frameworks). - are building a high-traffic consumer product → use a traditional web framework, you'll have more control. - need a pixel-perfect bespoke UI for end users → the generated UI is @@ -71,6 +90,10 @@ Common scenarios where it's a fit: - need real-time collaborative editing (Figma-style) → not what the realtime plugin solves. +The reasoning behind the first five, for the open runtime ObjectOS is +built on, is on +[When to use ObjectStack](https://objectstack.ai/docs/concepts/when-to-use). + ## Compared to what you're probably using ### vs. Retool / Appsmith / Internal @@ -102,8 +125,8 @@ Common scenarios where it's a fit: | | Salesforce | ObjectOS | |---|---|---| -| Data model | Objects + fields + relationships | Same | -| Permissions | Profile + permission sets + sharing rules + FLS | **Same vocabulary**, declarative TypeScript | +| Data model | Objects + fields + relationships, configured in the platform | Objects, fields and relations in one open ontology — exportable, and runnable on the Apache-2.0 ObjectStack runtime | +| Permissions | Profile + permission sets + sharing rules + FLS | A familiar vocabulary — permission sets, positions, sharing rules, FLS — declared in the ontology and enforced on every REST call, UI click and agent tool call | | Per-user cost | $150-300/user/month | Viewers and non-AI users free; you pay for AI seats only | | Customization | Apex + Lightning + flows | TypeScript + flows | | Where it runs | Their cloud, period | ObjectOS Cloud, or your infrastructure (ObjectOS Enterprise) | @@ -149,8 +172,8 @@ production today serves tens of thousands of internal users across multiple regions with Postgres + S3 + Redis. All of them run the same software. -Start on [ObjectOS Cloud](https://www.objectos.ai), or boot the open -ObjectStack runtime with `npx @objectstack/cli init my-app`, and decide in -5 minutes. If it's not for you, you've burned 5 minutes. +Start on [ObjectOS Cloud](https://www.objectos.ai), or scaffold a project +on the open ObjectStack runtime with `npm create objectstack@latest my-app`, +and decide in 5 minutes. If it's not for you, you've burned 5 minutes. [**Try the Quickstart →**](/docs/quickstart)