Referencia
Índice de paquetes
Once paquetes npm, qué exporta cada uno y cuáles funcionan sin ningún LLM.
Handbooks es un monorepo de once paquetes. Cuatro de ellos nunca tocan un LLM y son útiles por sí solos.
| Paquete | Función | ¿LLM? | Docs |
|---|---|---|---|
@handbooks/core | Modelo de datos, esquemas zod, registro de configuración, utilidades | ❌ | README |
@handbooks/analyzer | Extracción estática del grafo de llamadas multilenguaje | ❌ | README |
@handbooks/llm | Cliente compatible con OpenAI, caché, actor–crítico, mock | ✅ | README |
@handbooks/pipeline | El pipeline de generación, fases 1–3 | ✅ | README |
@handbooks/renderer | Markdown, HTML, índice para agentes, llms.txt | ❌ | README |
@handbooks/skill | Empaquetado SKILL, validación, hashes de deriva | ❌ | README |
@handbooks/planner | Agente de planificación de solo lectura | ✅ | README |
@handbooks/patcher | Aplicación byte-exacta, copias de seguridad, rollback | ❌ | README |
@handbooks/resync | Roll-forward incremental | ✅ | README |
@handbooks/studio | Interfaz web local | ✅ | README |
@handbooks/cli | El comando handbook | — | README |
Los tres más útiles por sí solos
@handbooks/analyzer — un grafo de llamadas para 18 lenguajes
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: '',
},
);Sin LLM, sin red, sin compilación nativa.
@handbooks/patcher — aplicar un plan de edición de forma segura
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 })
}El formato del plan está documentado en Aplicar cambios. Nada
obliga a que el plan provenga de @handbooks/planner: puedes escribir uno a mano.
@handbooks/renderer — renderizar cualquier HandbookModel
import { renderMarkdownHandbook, renderAgentSite, renderLlmsTxt } from '@handbooks/renderer';
renderMarkdownHandbook(model, 'out/');
renderAgentSite(model, 'out/agent');
renderLlmsTxt(model, 'out/');HandbookModel es el único contrato. Rellena uno como quieras y el renderizado, el
empaquetado del skill y la planificación funcionan todos.
Exportaciones clave de un vistazo
// @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 · JobRunnerInstalación
pnpm add @handbooks/analyzer # or npm / yarnTodos los paquetes son solo ESM ("type": "module"), incluyen declaraciones de tipos,
requieren Node ≥ 20.11 y tienen licencia MIT. Las versiones de terceros se fijan una sola
vez en el catálogo del workspace, así que dos paquetes nunca pueden acabar en dos
versiones de la misma librería.