Ausgaben rendern
Markdown, eine HTML-Site, eine einzelne in sich geschlossene Seite, der Agent-Locator-Index und llms.txt — alles deterministisch, alles kostenlos wiederholbar.
handbook render --work <workdir> [--title <t>] [--html] [--html-single] [--agent-site] [--llms-txt]Kein LLM. Kein Netzwerk. Deterministisch. Gleiches Modell hinein, byte-identische Dateien heraus — deshalb gehört dieser Schritt in die CI, bei jedem Commit.
Die fünf Ausgaben
Wird immer geschrieben.
<out>/
overview.md system prose + a mermaid stage map + "see also" links
index.md every stage, nested by depth, a paragraph each
<stage-id>.md one page per content-bearing stage
register.md the cross-stage state table (only when registers exist)Eine Etappenseite enthält die Etappenzusammenfassung, Links zu Unteretappen und dann ihre Dateien — gruppiert und geordnet, wie Phase 2c es entschieden hat, jede gerendert als Dateikarte: Zweck, Rolle, Lebenszyklus, Aufruf-Fakten und bei tiefen Karten Notizen pro Funktion.
Zwei Verhaltensweisen, die man kennen sollte:
- Veraltete Seiten werden aufgeräumt. Etappen-IDs ändern sich zwischen Generierungen; jeder Render entfernt zuerst die Seiten des vorherigen Renders, sodass eine umbenannte Etappe keine Geisterseite hinterlässt, die der Skill-Packager einsammeln könnte.
- Der Register-Abschnitt pro Etappe ist idempotent — er wird unter einem Marker angehängt, und nur, wenn der Marker fehlt. Erneutes Rendern stapelt nie Duplikate.
Links auf Ihren Quellcode
handbook render --work $WORK --source-base-url https://github.com/me/repo/blob/mainJeder Dateipfad im Handbooks wird zu einem Link auf die echte Datei. Richten Sie die URL
statt auf main auf ein Tag oder einen Commit-SHA, wenn das Handbook auf genau den Code
verweisen soll, aus dem es generiert wurde.
Ohne dieses Flag enthält die Ausgabe überhaupt keine externen URLs — der richtige Standard für eine private Codebasis.
Titel und Sprachen
handbook render --work $WORK --title "Payments Service — Engineering Handbook"Die Sprache des Erzähltexts wird zur Generierungszeit festgelegt (--narrate-lang) und in
phase3/narration.json gespeichert. Der Renderer liest sie von dort — jedes Label, jede
Überschrift und jeder Tabellenkopf wird passend lokalisiert. Die Struktur ist in beiden
Sprachen identisch, sodass Tooling, das die Ausgabe liest, nicht wissen muss, welche
Sprache vorliegt.
Erneutes Rendern als Gewohnheit
Rendern ist kostenlos und deterministisch — verdrahten Sie es also mit der CI:
- run: handbook render --work work/api --title "API Handbook" --html --agent-site --llms-txt
- run: handbook skill --handbook work/api/handbook --out skills/api --name api \
--work work/api --source . --agent-dir work/api/handbook/agent
- run: handbook validate --skill skills/api --source .Siehe CI-Integration.
Die HTML-Site veröffentlichen
Die Ausgabe ist ein statisches Verzeichnis mit relativen Links und ohne externe Assets, daher funktioniert jeder statische Host:
# GitHub Pages
cp -R work/api/handbook/html/* docs-site/ && git add docs-site
# Netlify / Vercel / S3 / nginx
npx serve work/api/handbook/htmlLiefern Sie llms.txt im Site-Root aus, damit Agenten sie finden.
Ein Handbook generieren
Detailgrad, Synthesemodus und Strategie wählen; Phasen einzeln ausführen; Läufe fortsetzen; und was zu tun ist, wenn das Ergebnis falsch ist.
Für Ihren Agenten paketieren
Ein gerendertes Handbooks in ein SKILL-Paket mit Drift-Erkennung verwandeln und in einen Coding-Agenten einbinden.