Skip to content

Specifiche leggibili dalle macchine

Uno JSON Schema per la configurazione e un documento OpenAPI per l'API, entrambi generati dal codice e controllati in CI, così un agente di coding può configurare Potato senza inventarsi opzioni.

Potato pubblica due contratti generati e verificabili dalle macchine accanto alla documentazione discorsiva. Entrambi sono prodotti dal codice in esecuzione anziché mantenuti a mano, quindi descrivono ciò che Potato fa davvero e non ciò che qualcuno ricordava l'ultima volta che ha modificato una pagina.

Se stai puntando un agente di coding su Potato, questi due più llms.txt sono le cose di maggior valore da dargli.

ArtefattoChe cosa descrive
JSON Schema della configurazioneOgni chiave, tipo di annotazione e tipo di display validi in un config.yaml di task
Specifica OpenAPI 3.1Ogni endpoint HTTP che il server registra

Lo schema di configurazione

La versione 2.8.0 copre 159 chiavi di configurazione di primo livello, 61 tipi di annotazione e 24 tipi di display, più i condizionali per tipo, così a uno schema constant_sum viene detto che servono le labels prima che il server lo rifiuti.

Aggiungi la modeline come prima riga di qualunque configurazione e il tuo editor valida mentre scrivi, su VS Code, JetBrains, Zed e Helix:

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

Ogni configurazione distribuita nel repository di Potato la porta, e il playground la emette a ogni download.

In CI:

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

Oppure con il validatore locale, che segnala in più le chiavi sconosciute:

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

La specifica dell'API

419 path e 456 operazioni, ricavati percorrendo la mappa delle rotte Flask attive anziché scrivendoli a mano. I blueprint attivati dalla configurazione vengono registrati su app usa e getta per non essere omessi in silenzio, e l'autenticazione per endpoint è recuperata con una scansione dell'AST.

Per dare la scala: il riferimento precedente, scritto a mano, copriva 84 endpoint a fronte di oltre 400 rotte registrate.

La CI fallisce se le due cose divergono

Entrambi gli artefatti vengono rigenerati e confrontati in CI. Uno schema che può divergere dal codice è peggio di nessuno schema, perché verrà creduto.

Perché conta adesso

Il fallimento più comune quando un LLM scrive una configurazione Potato è inventare un annotation_type che non esiste. Distribuire uno JSON Schema che editor e agenti risolvono offline risolve il problema alla radice.

Il generatore di configurazioni di questo sito si basa sulla stessa idea: il playground legge i registri di Potato e può emettere solo chiavi che vi compaiono, con un'infrastruttura che passa ogni configurazione generata attraverso validate_cli --strict.

Correlati