Referenz
Paketverzeichnis
Elf npm-Pakete, was jedes exportiert und welche davon ganz ohne LLM funktionieren.
Handbooks ist ein Monorepo aus elf Paketen. Vier davon fassen nie ein LLM an und sind ganz für sich allein nützlich.
| Paket | Rolle | LLM? | Doku |
|---|---|---|---|
@handbooks/core | Datenmodell, zod-Schemata, Konfigurations-Registry, Utilities | ❌ | README |
@handbooks/analyzer | Mehrsprachige Extraktion des statischen Aufrufgraphen | ❌ | README |
@handbooks/llm | OpenAI-kompatibler Client, Cache, Akteur-Kritiker, Mock | ✅ | README |
@handbooks/pipeline | Die Generierungs-Pipeline, Phasen 1–3 | ✅ | README |
@handbooks/renderer | Markdown, HTML, Agent-Index, llms.txt | ❌ | README |
@handbooks/skill | SKILL-Verpackung, Validierung, Drift-Hashes | ❌ | README |
@handbooks/planner | Nur lesender Planungsagent | ✅ | README |
@handbooks/patcher | Byte-genaues Anwenden, Sicherungen, Rollback | ❌ | README |
@handbooks/resync | Inkrementelles Nachziehen | ✅ | README |
@handbooks/studio | Lokale Weboberfläche | ✅ | README |
@handbooks/cli | Der handbook-Befehl | — | README |
Die drei nützlichsten für sich allein
@handbooks/analyzer — ein Aufrufgraph für 18 Sprachen
import { registerBuiltinAdapters, discoverAll, getAdapter, buildGraph } from '@handbooks/analyzer';
registerBuiltinAdapters();
const byLanguage = discoverAll('/path/to/repo');
const analyses = [];
for (const [lang, files] of Object.entries(byLanguage)) {
analyses.push(await getAdapter(lang).analyze(files, '/path/to/repo'));
}
const { graph, stats } = buildGraph(
{ functions: analyses.flatMap((a) => a.functions), edges: analyses.flatMap((a) => a.edges) },
{
sourceRoot: '/path/to/repo',
scannedFiles: Object.values(byLanguage).flat(),
language: 'multi',
defaultExt: '',
},
);Kein LLM, kein Netzwerk, keine native Kompilierung.
@handbooks/patcher — einen Änderungsplan sicher anwenden
import { applyPlan, rollback, parsePlan } from '@handbooks/patcher';
const problems = parsePlan(planText).problems; // lint a plan without applying it
const dry = applyPlan({ sourceRoot, plan: planText, dryRun: true });
if (dry.ok) {
const result = applyPlan({ sourceRoot, plan: planText });
// rollback(result.backupDir!, { expectedSourceRoot: sourceRoot })
}Das Planformat ist unter Änderungen anwenden dokumentiert.
Nichts verlangt, dass der Plan von @handbooks/planner stammt — du kannst einen von Hand
schreiben.
@handbooks/renderer — beliebiges HandbookModel rendern
import { renderMarkdownHandbook, renderAgentSite, renderLlmsTxt } from '@handbooks/renderer';
renderMarkdownHandbook(model, 'out/');
renderAgentSite(model, 'out/agent');
renderLlmsTxt(model, 'out/');HandbookModel ist der einzige Vertrag. Fülle eines, wie du magst, und Rendern,
Skill-Verpackung und Planung funktionieren allesamt.
Wichtige Exporte auf einen Blick
// @handbooks/core — the vocabulary
CodeGraph · FunctionNode · CallEdge · AdapterCapabilities
FileCard · Skeleton · Assignment · Organization · Narration · RegisterEntry
HandbookModel · StageTree · coerceRole
resolveConfig · settingsFor · envName · scopedEnvName · loadConfigFile · applyEnvFiles
writeFileAtomic · readValidatedJson · pLimit · withRetry · withDirLock · sha256Hex
// @handbooks/analyzer — the parser
registerBuiltinAdapters · registerAdapter · getAdapter · availableLanguages
discoverAll · adapterForFile · buildGraph · writeGraphArtifacts · buildNavPack
// @handbooks/llm — the model seam
ChatClient · OpenAiChatClient · CachedChatClient · MockChatClient
resolveLlmEnv · llmConfigFromValues · actorCriticLoop · ROLE_PROMPTS
// @handbooks/pipeline — generation
generateHandbook · loadHandbookModel · runPhase1 · generateCards
synthesizeSkeleton · synthesizeWithDoctor · assignFiles · organizeStages
narrate · extractRegisters · classifyMembers · WorkDir
// @handbooks/renderer — presentation
renderMarkdownHandbook · renderHtmlSite · renderSinglePageHtml
renderAgentSite · renderLlmsTxt · HandbookView · stageMapMermaid
// @handbooks/skill — packaging
buildSkill · validateSkill
// @handbooks/planner — localization
runPlanner · handbookDirFromSkill · parseDeclarations · ReadOnlyTools
// @handbooks/patcher — execution
applyPlan · rollback · listBackups · parsePlan
// @handbooks/resync — roll-forward
resyncHandbook · loadCase · diffGraphs · detectCardDetail · loadCorrections
// @handbooks/studio — the UI
startStudio · createStudioServer · StateStore · JobRunnerInstallation
pnpm add @handbooks/analyzer # or npm / yarnJedes Paket ist reines ESM ("type": "module"), liefert Typdeklarationen mit, verlangt
Node ≥ 20.11 und steht unter MIT-Lizenz. Drittanbieter-Versionen sind einmal im
Workspace-Katalog festgelegt, sodass zwei Pakete nie auf zwei Versionen derselben
Bibliothek landen können.