Plattform und Server

Jede PocketContext-Anwendung läuft in einem einzelnen Go-Binary, pocketcontext, das PocketBase für SQLite-Speicher, Authentifizierung und REST-Änderungen an Datensätzen einbettet. PocketContext ergänzt einen nur lesenden SQL-Endpunkt, /api/context/query, damit ein KI-Assistent Daten direkt zusammenführen und aggregieren kann. Schreibzugriffe laufen weiter über die Records-API, wo die Regeln und Hooks der Anwendung ausgeführt werden.

Eine Anwendung ist ein Ordner mit Regeln, die der Server lädt, und keine zweite Art von Server. In der Produktion ist jede Anwendung ein eigener Prozess, eine eigene Datenbank und ein eigener Google-Client. Die Datei POCKETCONTEXT_VERSION in diesem Ordner ist der Server-Commit, mit dem die Anwendung getestet wurde. Ein neueres Server-Binary zu bauen aktualisiert die Tabellen der Anwendung nicht.

flowchart TD
  migrations["pb_migrations — Tabellen und Regeln"]
  hooks["pb_hooks — zusätzliche Prüfungen"]
  config["pocketcontext.json — was SQL sehen darf"]
  skill["Skill und CLI"]
  ui["Browserseiten"]
  pb["PocketBase — Anmeldung, Datensätze, Dateien"]
  sql["SQL-Leser — nur Fragen"]
  snap["gefilterte Kopie — nur die Zeilen dieser Person"]
  data["pb_data — die Datenbank auf der Festplatte"]

  migrations --> pb
  hooks --> pb
  config --> sql
  skill --> sql
  skill --> pb
  ui --> pb
  pb --> data
  sql --> data
  sql --> snap
  snap --> data

Mit SQL lesen, über die API schreiben

sequenceDiagram
  participant A as KI-Assistent
  participant R as /api/context/query
  participant W as /api/collections/.../records
  participant D as Datenbank

  A->>R: ein SELECT, mit einem Bearer-Token
  R->>D: nur lesende Verbindung
  D-->>A: Spalten, Zeilen, abgeschnitten?

  A->>W: einen Datensatz per POST oder PATCH
  W->>D: PocketBase-Regeln und Hooks
  D-->>A: gespeicherter Datensatz

SQL nimmt eine Anweisung an. Joins, Aggregate und gewöhnliche SQLite-Funktionen sind erlaubt. Schreibzugriffe, Schemaänderungen, Transaktionen und PRAGMA werden abgelehnt. Die Standardgrenzen sind 2 Sekunden, 500 Zeilen und 1 MiB Ergebnis. Wird die Zeilengrenze erreicht, enthält die Antwort truncated: true. Die Antwort ist dann unvollständig.

Das Bearer-Token stammt aus der Collection, die in authCollection genannt ist, oft users oder agents. Ein Superuser-Token umgeht SQL nicht.

Gemeinsamer Arbeitsbereich oder eine private Kopie

Die Anwendung entscheidet, welche Zeilen ein KI-Assistent sehen darf. Der Server erfindet diese Regel nicht.

flowchart TD
  login[Angemeldetes Konto]
  login --> mode{Wie diese Anwendung konfiguriert ist}
  mode -->|gemeinsamer Arbeitsbereich| all[Jedes Konto kann die konfigurierten Spalten lesen]
  mode -->|gefilterte Snapshots| copy[Eine private Kopie nur der Zeilen dieser Person]
  all --> query[Die SQL-Abfrage läuft]
  copy --> query

TaskContext, DealContext, RaiseContext und LinkContext sind gemeinsame Arbeitsbereiche: Teammitglieder sehen dieselben Zeilen. PeopleContext, AccountContext, WikiContext, NotifyContext und ChatContext filtern, jede mit ihrer eigenen Regel. Bei gefilterten Snapshots läuft jede Abfrage gegen eine eigene Datenbank, die nur die Zeilen enthält, die dieses Konto sehen darf. Die Kopie wird wiederverwendet, bis die echte Datenbank eine Änderung festschreibt. Regeln, die von der Uhrzeit abhängen, werden nicht wiederverwendet.

Suche, Traces und die Dateien auf der Festplatte

Einige Anwendungen schalten POST /api/context/search ein. Der KI-Assistent sendet einen Indexnamen und Text, kein SQL, und Volltexttabellen bleiben vom SQL-Endpunkt fern. Anwendungen mit gefilterten Snapshots bauen einen privaten Index aus den Zeilen dieser Person.

Tracing ist aus, außer pocketcontext.json verlangt es. Eine abgeschlossene Anfrage kann als eine JSON-Zeile geschrieben werden: Route, Status, Benutzer-ID, Dauer und benannte Schritte wie prepare, execute und scan. Die Zeile enthält keine Passwörter, keine Anfragekörper und keine Abfrageergebnisse. SQL-Text ist optional und begrenzt, weil eine Abfrage private Werte enthalten kann. Der Server sendet diese Zeile nicht an ObserveContext. Der eigene Client der Anwendung lädt sie später hoch. Siehe Beobachten.

pb_data enthält die Datenbank und die Zugangsdaten und bleibt außerhalb von Git. Sichere es vor einem Upgrade. PocketBase ist noch vor 1.0. Lies deshalb die Upgrade-Hinweise, bevor du die Version wechselst. Ein Superuser kann Schreibzugriffe über die Wartungs-API einfrieren, ohne den Prozess zu stoppen. Lesezugriffe laufen weiter, und neue Änderungen warten, bis die Sperre aufgehoben wird. Eine Anwendung muss diesen Vertrag übernehmen, bevor sie ihn für eine Migration nutzt.

Installationsprogramme für Linux (amd64 und arm64) und macOS 15 oder neuer auf Apple Silicon stehen in der Server-Anleitung.

Werkzeuge neben dem Server