Installation

Voraussetzungen

Das ist tatsächlich die ganze Liste. Es gibt keinen nativen Kompilierschritt — die Sprachparser werden als WebAssembly ausgeliefert, also kein node-gyp, keine Compiler-Toolchain, kein Python.

Option 1 — aus einem Klon (empfohlen zum Evaluieren)

git clone <this repo>
cd handbooks
pnpm install
pnpm build

Danach die CLI bequem aufrufbar machen:

alias handbook="node $(pwd)/packages/cli/dist/main.js"
handbook --help

Oder den Alias ganz weglassen und die pnpm-Shortcuts verwenden: Sie bauen zuerst inkrementell (etwa 0,4 s, sobald warm) und reichen Flags direkt durch:

pnpm analyze --source ~/code/myrepo --work work/myrepo
pnpm handbook --help

Option 2 — als globale CLI

npm i -g @handbooks/cli
handbook --help

Option 3 — Docker, ganz ohne lokales Node

docker build -t handbook:local .

# HANDBOOK_SOURCE=/src and HANDBOOK_WORK=/work are baked into the image,
# so you only mount volumes — no --source/--work needed:
docker run --rm -v "$PWD:/src:ro" -v handbook-work:/work handbook:local analyze

Siehe den Docker-Leitfaden für Studio, Umgebungen und die Einschränkung, dass nur localhost funktioniert.

Option 4 — als Bibliotheken

Jede Fähigkeit ist ein veröffentlichtes Paket, das sich einzeln nutzen lässt. Analyzer, Renderer, Skill-Packager und Patcher berühren nie ein LLM und funktionieren daher eigenständig:

pnpm add @handbooks/analyzer   # static call graphs, 18 languages
pnpm add @handbooks/renderer   # a HandbookModel → markdown / HTML / agent index
pnpm add @handbooks/patcher    # apply byte-exact edit plans with rollback

Siehe den Paketindex.

Den LLM-Endpunkt konfigurieren

Phase 1 — die statische Analyse — braucht nie einen Schlüssel. Alles andere schon.

export OPENAI_API_KEY=sk-...                        # required for phases 2 and 3
export OPENAI_MODEL=gpt-4o-mini                     # default: gpt-4o-mini
export OPENAI_BASE_URL=https://api.openai.com/v1    # or your own endpoint

Lieber eine Datei als Shell-Exporte

Die CLI lädt automatisch ./.env aus dem Verzeichnis, in dem sie ausgeführt wird. Shell-Variablen gewinnen immer — eine .env ist also ein Standardwert, kein Override.

OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o-mini
OPENAI_BASE_URL=https://api.openai.com/v1

.env.example kopieren — sie wird aus der Einstellungs-Registry generiert, listet also jede Variable, die tatsächlich existiert, samt Standardwert, und jede Zeile beginnt auskommentiert, sodass das Kopieren gefahrlos ist.

Für mehrere Umgebungen, Overrides pro Befehl und handbook.config.yaml siehe Konfiguration.

Die Installation prüfen

Zwei Befehle, in dieser Reihenfolge.

1. Läuft die Toolchain überhaupt?

pnpm demo

Die volle Pipeline, offline, gegen ein mitgeliefertes Beispielprojekt und ein mitgeliefertes Mock-LLM. Wenn das durchläuft, ist die Installation in Ordnung.

2. Ist der Endpunkt erreichbar und konfiguriert?

handbook config --command generate

Das gibt jede Einstellung aus, ihren aufgelösten Wert und aus welcher Schicht er stammt — Flag, Umgebungsvariable, Konfigurationsdatei oder Standardwert. Geheimnisse werden maskiert.

handbook config --check    # exit code 2 if anything is invalid or missing

Weiter