Konfigurationsreferenz

Diese Seite ist die Übersetzung einer generierten Seite. Das englische Original wird von pnpm run config:docs aus der Einstellungs-Registry generiert und durch einen Drift-Test geschützt; diese Übersetzung wird von Hand gepflegt — ändert sich das Original, aktualisiere sie mit.

Vorrang

Jede Einstellung wird über dieselben Schichten aufgelöst, höchste Priorität zuerst: Flag > Shell-Umgebung > .env > handbook.config.yaml > Standardwert. Die erste Schicht, die einen Wert liefert, gewinnt, und jede darunterliegende Schicht wird für diese Einstellung ignoriert. Führe handbook config aus — oder handbook config --command <name>, um nur einen Unterbefehl zu sehen —, um zu prüfen, was tatsächlich aufgelöst wurde und aus welcher Schicht es kam.

Benennung

Ein einziger camelCase-key in der Registry steuert alle drei Oberflächen zugleich: ein Flag, eine Umgebungsvariable und einen Konfigurationsdatei-Schlüssel. Stellt man einer davon einen Befehlsnamen voran, beschränkt das diese Oberfläche auf einen Unterbefehl, und es ist bei allen dreien dieselbe Transformation — HANDBOOK_<KEY> wird zu HANDBOOK_<COMMAND>_<KEY>, und key wird zu <command>Key, ob flach geschrieben oder eine Ebene unter <command>: verschachtelt. Eine unten mit (befehlsbezogen) markierte Einstellung akzeptiert nur den präfixierten Env-Namen, weil sich ihre Bedeutung je Befehl ändert (--out, --lang im skill-Paket).

Bootstrap

Drei Einstellungen auf oberster Ebene zeigen auf die Schichten oben und stehen selbst außerhalb der Registry; sie werden einmal vor allen anderen Einstellungen aufgelöst — weshalb auch keine von ihnen von dem gesetzt werden kann, was sie lädt: ein --env-Schlüssel in handbook.config.yaml, eine --env-file-Zeile in .env oder ein --config-Schlüssel in eben dieser Datei hätten niemanden mehr, der sie liest.

• --env <name> (oder HANDBOOK_ENV) wählt eine umgebungsspezifische Kaskade — als einzige der drei mit sowohl einer Flag- als auch einer Umgebungsvariablen-Form, da sie eine Umgebung benennt, statt auf genau eine Datei zu zeigen.
• --env-file <path> lädt genau diese eine Datei und umgeht die Kaskade unten.
• --config <path> benennt genau eine Konfigurationsdatei und umgeht die umgebungsbewusste Suche unten (Standard: die nächstgelegene Datei der handbook.config.yaml-Familie, gefunden durch Hochlaufen vom Arbeitsverzeichnis, mit Halt an einer Repository-Grenze).

Die .env-Kaskade

Ohne --env-file lädt die CLI statt einer festen Datei eine Kaskade von .env*-Dateien, höchster Vorrang zuerst. Die bestehende applyEnvFile-Regel — einen bereits gesetzten Schlüssel nie überschreiben — ist es, die aus einer Kaskade nicht mehr macht als „rufe sie in dieser Reihenfolge auf, die erste Datei, die einen Schlüssel setzt, gewinnt“:

Zeilen 2 und 3 gelten nur, wenn --env/HANDBOOK_ENV eine Umgebung benennt. Ist keines von beiden gesetzt, laden nur die Zeilen 4 und 5 — genau das, was auch vor dieser Kaskade geladen wurde, sodass ein bestehendes Setup ohne .env.local überhaupt keine Änderung sieht.

Konfigurationsdatei-Suche mit einer Umgebung

Von --config abgesehen läuft die Suche weiterhin vom Arbeitsverzeichnis nach oben und hält an einer Repository-Grenze, prüft aber in jedem besuchten Verzeichnis nun zuerst auf handbook.config.<name>.{yaml,yml,json} (nur wenn eine Umgebung benannt ist), bevor die schlichte handbook.config.yaml usw. an die Reihe kommt — eine benannte Datei schlägt also stets eine schlichte Datei im selben Verzeichnis, selbst wenn eine schlichte Datei auf einer Ebene näher am Arbeitsverzeichnis existiert. Ist keine Umgebung benannt, bleibt die Suche unverändert.

Führe handbook config aus, um zu sehen, welche Umgebung aktiv ist und welche Dateien sie genau geladen hat, in Vorrangreihenfolge — eine Kaskade über vier Wertschichten sind zu viele mögliche Quellen, um sie aus dem Kopf zu verfolgen, und eine Schicht, die dieser Befehl nicht zeigen kann, unterscheidet sich nicht von einer Schicht, die nicht funktioniert.

Durchgerechnetes Beispiel für readWorkers (Flag --read-workers <n>, Standard 12):

Die Konfigurationsdatei-Formen sind austauschbar: ein flaches readWorkers: ... und ein verschachteltes generate: { readWorkers: ... } bedeuten dasselbe, weil die Datei vor dem Lesen durch dieselbe camelCase-Verkettung flachgeklopft wird.

analyze

generate

render

skill

validate

plan

apply

rollback

resync

studio

config