Referência
Índice de pacotes
Onze pacotes npm, o que cada um exporta e quais deles funcionam sem nenhum LLM.
O Handbooks é um monorepo de onze pacotes. Quatro deles nunca tocam em um LLM e são úteis por conta própria.
| Pacote | Papel | LLM? | Docs |
|---|---|---|---|
@handbooks/core | Modelo de dados, esquemas zod, registro de configuração, utilitários | ❌ | README |
@handbooks/analyzer | Extração estática do grafo de chamadas multilinguagem | ❌ | README |
@handbooks/llm | Cliente compatível com OpenAI, cache, ator–crítico, mock | ✅ | README |
@handbooks/pipeline | O pipeline de geração, fases 1–3 | ✅ | README |
@handbooks/renderer | Markdown, HTML, índice para agentes, llms.txt | ❌ | README |
@handbooks/skill | Empacotamento SKILL, validação, hashes de deriva | ❌ | README |
@handbooks/planner | Agente de planejamento somente leitura | ✅ | README |
@handbooks/patcher | Aplicação byte-exata, backups, rollback | ❌ | README |
@handbooks/resync | Roll-forward incremental | ✅ | README |
@handbooks/studio | Interface web local | ✅ | README |
@handbooks/cli | O comando handbook | — | README |
Os três mais úteis por conta própria
@handbooks/analyzer — um grafo de chamadas para 18 linguagens
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: '',
},
);Sem LLM, sem rede, sem compilação nativa.
@handbooks/patcher — aplicar um plano de edição com segurança
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 })
}O formato do plano está documentado em Aplicando mudanças.
Nada exige que o plano tenha vindo do @handbooks/planner — você pode escrever um à mão.
@handbooks/renderer — renderizar qualquer HandbookModel
import { renderMarkdownHandbook, renderAgentSite, renderLlmsTxt } from '@handbooks/renderer';
renderMarkdownHandbook(model, 'out/');
renderAgentSite(model, 'out/agent');
renderLlmsTxt(model, 'out/');HandbookModel é o único contrato. Preencha um do jeito que quiser e a renderização, o
empacotamento do skill e o planejamento todos funcionam.
Exportações principais num relance
// @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 · JobRunnerInstalação
pnpm add @handbooks/analyzer # or npm / yarnTodo pacote é ESM-only ("type": "module"), publica declarações de tipos, exige Node
≥ 20.11 e é licenciado sob MIT. As versões de terceiros são fixadas uma única vez no
catálogo do workspace, então dois pacotes nunca podem acabar em duas versões da mesma
biblioteca.