Inicio rápido
Ejecuta la cadena de herramientas completa de principio a fin en unos treinta segundos — sin conexión, sin clave de API y sin gastar un solo token.
La forma más rápida de entender lo que hace Handbooks es verlo hacerlo. Esto ejecuta el pipeline completo — análisis, generación, renderizado, empaquetado, validación — contra un proyecto de ejemplo incluido, usando un servidor mock de LLM también incluido.
Sin clave de API. Sin red. Cero tokens.
Paso 1 — Ejecútalo
git clone <this repo> && cd handbooks
pnpm install
pnpm build
pnpm demoPaso 2 — Lee lo que imprimió
== build ==
== start mock LLM (offline; prose will be placeholder text) ==
== 1. analyze (no LLM) ==
{ "language": "multi", "files": 5, "functions": 23, "edgesKept": 31, "edgesDropped": 4, "filesUnparsed": 0 }
== 2. generate (phases 2+3) ==
{ "phasesRun": ["2a","2b","2c","3"], "nCards": 5, "nStages": 4, "nRegisters": 2 }
== 3. render markdown + HTML site + agent index + llms.txt ==
== 4. package as an agent SKILL (with the agent locator pages) ==
== 5. validate the SKILL ==
validate: OKLa prosa será un sinsentido — es lo esperado
El mock de LLM devuelve texto de relleno. La estructura es completamente real — etapas, asignación de archivos, hechos de llamadas, rangos de líneas, la tabla de registros, cada enlace. Solo las frases son falsas. Esa es exactamente la separación sobre la que está construido este proyecto: los hechos vienen del parser, la prosa viene de un modelo.
Paso 3 — Abre los resultados
open examples/work/demo/handbook/overview.md # the markdown handbook
open examples/work/demo/handbook/html/overview.html # the multi-page HTML site
open examples/work/demo/handbook/handbook.html # the whole thing in one file
open examples/work/demo/skill/SKILL.md # the agent SKILL packageCosas que vale la pena mirar en concreto:
| Abre esto | Y fíjate en |
|---|---|
handbook/overview.md | Un mapa de etapas en mermaid generado a partir del grafo de llamadas |
handbook/index.md | Cada etapa, anidada, cada una con un párrafo |
handbook/register.md | El estado transversal a las etapas, con las etapas que tocan cada pieza |
handbook/agent/index.md | El índice para agentes — recetas de búsqueda, la tabla de etapas, cobertura. Se lee entero |
handbook/agent/symbols.tsv | Cada símbolo → path:startLine-endLine. Esto es lo que las páginas en prosa nunca tuvieron |
skill/references/coverage.json | Un hash de contenido por archivo. Esta es la señal de deriva. |
work/demo/phase1/dropped-calls.json | Llamadas que el analizador no pudo resolver, conservadas y categorizadas en vez de adivinadas |
work/demo/phase1/scan-coverage.json | Archivos que el analizador no pudo leer o parsear del todo. Un [] aquí significa que los cinco parsearon |
Paso 4 — Mira bajo el capó
Todo lo que produjo el pipeline es JSON y YAML plano dentro del directorio de trabajo:
ls examples/work/demo/
# phase1/ phase2/ phase3/ handbook/ skill/ run-manifest.json
cat examples/work/demo/phase1/graph.json | head -40
cat examples/work/demo/phase2/skeleton.yaml
cat examples/work/demo/run-manifest.json # model, phases, timings, token usageCada uno de ellos se valida contra un esquema al leerse. Si editas uno a mano y lo dejas en un estado inválido, el siguiente comando te dice qué archivo y por qué — el error no se propaga.
Las otras demos
pnpm demo:self # this repo as its own input, against the mock LLM
pnpm demo:self:real # same, but against the real endpoint from .env
pnpm mock-llm # just the mock server, on port 8099pnpm demo:self es la más interesante de leer: analiza once paquetes TypeScript reales,
así que la estructura de etapas que produce es un mapa genuino de una base de código
genuina.
Qué acaba de pasar
analyzeparseó con tree-sitter cada archivo que pudo leer y produjo un grafo de llamadas tipado, y escribió enphase1/scan-coverage.jsonlo que no pudo leer. Sin LLM.generateescribió una ficha por archivo, sintetizó un esqueleto de etapas, asignó cada archivo a una etapa, los agrupó y ordenó, y después narró de abajo hacia arriba y extrajo los registros de estado transversales a las etapas.renderconvirtió eso en markdown, un sitio HTML, una página autocontenida, el índice localizador para agentes yllms.txt. Sin LLM.skilllo reempaquetó como una SKILL de agente con un hash de contenido por archivo. Sin LLM.validatecomprobó la estructura, el contrato del frontmatter, los enlaces índice ↔ página de etapa y la frescura de los hashes. Sin LLM.
La demo se detiene ahí. La otra mitad — plan → apply → rollback → resync — se
cubre en Tu primer handbook y en
Planificar cambios.
A continuación
Instalación
Node 20.11 y pnpm: esa es toda la lista. Sin compilación nativa, sin Python, sin node-gyp — los parsers son WebAssembly.
Tu primer handbook real
Ocho pasos desde un repositorio que nunca has leído hasta un plan de cambios que puedes aplicar — con los checkpoints baratos en el lugar correcto.