Ein Feature hinzufügen¶
Vier Arten von Änderungen, und für jede gibt es an anderer Stelle ein ausgearbeitetes Beispiel. Diese Seite ist die Landkarte: was eine Änderung dieser Art berühren muss, und wo die ausführliche Fassung steht.
Einen neuen API-Endpunkt hinzufügen¶
Eine Anleitung, in den Guides
Einen API-Endpunkt hinzufügen ist das ausgearbeitete Beispiel — Schema, Modell, Repository, Service, Dependency, Route, Router, Migration, Tests. Hier steht bewusst keine zweite Fassung davon: zwei Fassungen für denselben Leser sind zwei Fassungen, die einander widersprechen.
Die Form, die sie lehrt, in einem Absatz: ein Schema je Operation
(*Create/*Update/*Read/*List), ein Modell auf Base, TimestampMixin
mit einem __repr__, ein Repository aus zustandslosen Funktionen, die
flush()/refresh() nutzen und niemals commit(), ein Service, der nur die
Session hält und Domain-Exceptions auslöst, eine Annotated-Dependency in
api/deps.py, und eine Route, die -> Any zurückgibt, während
response_model die Serialisierung übernimmt.
Einen eigenen CLI-Befehl hinzufügen¶
Befehle werden aus app/commands/ automatisch gefunden.
# app/commands/my_command.py
import click
from app.commands import command, success
@command("my-command", help="What this does")
@click.option("--name", "-n", required=True, help="Whose name")
def my_command(name: str) -> None:
"""One line, because `--help` prints it."""
success(f"Done: {name}")
success, error, warning und info sind die Ausgabehelfer — ein Befehl sagt
über sie, was geschehen ist, und nicht über print, damit sich jeder Befehl im
CLI gleich liest. So führen Sie ihn aus:
Ein neuer Befehl schuldet docs/commands.md eine Zeile
Diese Seite ist die Referenz, die ein Betreiber liest; ein Befehl, der dort fehlt, ist ein Befehl, den niemand findet.
Ein Tool hinzufügen, das der Agent aufrufen kann¶
Es gibt kein einzelnes Agent-Modul, an das sich ein @agent.tool hängen ließe.
Agents sind hier Daten, je Run aus den Capabilities zusammengesetzt, die ihr Spec
nennt — ein neues Tool kommt also als Teil einer Capability:
- Eine neue → Eine Capability hinzufügen.
- Ein weiteres Tool auf einer bereits bestehenden Capability → Ein Tool zu einer bestehenden Capability hinzufügen.
- Eine fremde API, die bereits einen MCP-Server veröffentlicht → gar kein Code, siehe MCP.
Ein Tool, das die Registry nicht deklariert, lässt sich weder gaten noch umbenennen
Die Liste in @register(tools=...) ist das, worauf die Freigabe je Tool und
die Umbenennung je Agent aufsetzen. Ein nicht deklariertes Tool läuft
trotzdem — es läuft nur ohne Gate, und genau das ist das Versagen, das es zu
vermeiden lohnt.
Was heute ausgeliefert wird, steht im Capability-Katalog.
Eine Datenbankmigration hinzufügen¶
make db-check überspringt sich selbst, wenn keine Datenbank lauscht
alembic check braucht eine, also gibt das Target eine Warnung aus und
beendet sich mit 0, wenn auf CHECK_DB_PORT keine Datenbank läuft — eine
Modelländerung ohne Migration besteht dann das lokale make check. Der Job
test in CI hat ein Postgres neben sich und überspringt deshalb nicht;
dort wird dieser Fehler tatsächlich gefangen. Führen Sie zuerst
make docker-db aus, wenn Sie die lokale Antwort wollen.
Autogenerate ist ein Entwurf, keine Antwort
Lesen Sie die Revision, bevor Sie sie committen, und geben Sie ihr ein
Downgrade, das sie auch wirklich rückgängig macht — make test-migrations
durchläuft die ganze Kette in beide Richtungen.