Skip to content

Maschinenlesbare Spezifikationen

Ein JSON Schema für die Konfiguration und ein OpenAPI-Dokument für die API, beide aus dem Code erzeugt und in der CI geprüft, damit ein Coding-Agent Potato konfigurieren kann, ohne Optionen zu erfinden.

Potato veröffentlicht neben der Fließtext-Dokumentation zwei erzeugte, maschinell prüfbare Verträge. Beide entstehen aus dem laufenden Code statt aus Handarbeit und beschreiben deshalb, was Potato tatsächlich tut, und nicht, woran sich jemand beim letzten Bearbeiten einer Seite erinnerte.

Wenn Sie einen Coding-Agenten auf Potato ansetzen, sind diese beiden plus llms.txt das Wertvollste, was Sie ihm mitgeben können.

ArtefaktWas es beschreibt
Konfigurations-JSON-SchemaJeden gültigen Schlüssel, Annotationstyp und Display-Typ in einer Task-config.yaml
OpenAPI-3.1-SpezifikationJeden HTTP-Endpunkt, den der Server registriert

Das Konfigurationsschema

Version 2.8.0 deckt 159 Konfigurationsschlüssel der obersten Ebene, 61 Annotationstypen und 24 Display-Typen ab, dazu typabhängige Bedingungen. Einem constant_sum-Schema wird also gesagt, dass es labels braucht, bevor der Server es ablehnt.

Setzen Sie die Modeline als erste Zeile einer Konfiguration, und Ihr Editor validiert beim Tippen — in VS Code, JetBrains, Zed und Helix:

yaml
# yaml-language-server: $schema=https://potatoannotator.readthedocs.io/en/latest/schemas/potato-config.schema.json

Jede im Potato-Repository ausgelieferte Konfiguration trägt sie, und der Playground gibt sie bei jedem Download mit aus.

In der CI:

bash
check-jsonschema --schemafile \
  https://potatoannotator.readthedocs.io/en/latest/schemas/potato-config.schema.json \
  path/to/config.yaml

Oder mit dem lokalen Validator, der zusätzlich unbekannte Schlüssel meldet:

bash
python -m potato.validate_cli --strict config.yaml

Die API-Spezifikation

419 Pfade und 456 Operationen, aus der laufenden Flask-Routenkarte abgelaufen statt von Hand geschrieben. Konfigurationsabhängige Blueprints werden auf Wegwerf-Apps registriert, damit sie nicht stillschweigend fehlen, und die Authentifizierung je Endpunkt wird per AST-Scan rekonstruiert.

Zur Einordnung: Die frühere handgeschriebene Referenz deckte 84 Endpunkte gegenüber über 400 registrierten Routen ab.

Die CI schlägt bei Abweichung fehl

Beide Artefakte werden in der CI neu erzeugt und verglichen. Ein Schema, das vom Code abweichen kann, ist schlechter als gar keines, denn ihm wird vertraut werden.

Warum das gerade jetzt zählt

Der häufigste Fehler, wenn ein LLM eine Potato-Konfiguration schreibt, ist das Erfinden eines annotation_type, den es nicht gibt. Ein JSON Schema auszuliefern, das Editoren und Agenten offline auflösen, behebt das an der Quelle.

Der Konfigurationsbaukasten dieser Website beruht auf derselben Idee: Der Playground liest Potatos Registries und kann nur Schlüssel ausgeben, die dort stehen, mit einem Prüfstand, der jede erzeugte Konfiguration durch validate_cli --strict schickt.

Verwandt