Instalação
Node 20.11 e pnpm são a lista inteira. Sem compilação nativa, sem Python, sem node-gyp — os parsers são WebAssembly.
Requisitos
| Node.js | ≥ 20.11 |
| pnpm | ≥ 9 |
| Um endpoint LLM | Apenas para as Phases 2 e 3. Qualquer um compatível com OpenAI. |
Essa é genuinamente a lista inteira. Não há nenhum passo de compilação nativa — os
parsers de linguagem são distribuídos como WebAssembly, então nada de node-gyp, nada de
toolchain de compilador, nada de Python.
Verifique sua versão do Node com node --version. Se você usa nvm, o repositório inclui um .nvmrc,
então nvm use escolhe a versão certa.
Opção 1 — a partir de um clone (recomendado enquanto você avalia)
git clone <this repo>
cd handbooks
pnpm install
pnpm buildDepois, torne a CLI conveniente de chamar:
alias handbook="node $(pwd)/packages/cli/dist/main.js"
handbook --helpOu dispense o alias por completo e use os atalhos do pnpm, que fazem antes um build incremental (cerca de 0,4 s depois de aquecido) e repassam as flags diretamente:
pnpm analyze --source ~/code/myrepo --work work/myrepo
pnpm handbook --helpPor que os atalhos fazem build primeiro
Todo pnpm <command> roda tsc -b antes da CLI. É a diferença entre depurar o seu código e
depurar um dist/ desatualizado — o que custa uma hora na primeira vez que acontece.
Opção 2 — como CLI global
npm i -g @handbooks/cli
handbook --helpOpção 3 — Docker, sem nenhum Node local
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 analyzeVeja o guia de Docker para o Studio, os ambientes e a ressalva de
funcionar apenas em localhost.
Opção 4 — como bibliotecas
Cada capacidade é um pacote publicado que você pode usar por conta própria. O analisador, o renderizador, o empacotador de skill e o patcher nunca tocam um LLM, então funcionam de forma autônoma:
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 rollbackVeja o índice de pacotes.
Configurando o endpoint de LLM
A Phase 1 — análise estática — nunca precisa de chave. Todo o resto precisa.
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 endpointEndpoints locais e sem chave
Use OPENAI_API_KEY=EMPTY para endpoints que não autenticam — vLLM, o shim compatível com OpenAI do Ollama,
um LiteLLM local. O cliente precisa de algo ali; EMPTY é a forma combinada de dizer "deliberadamente
nenhuma", e produz um erro claro em vez de um 401 confuso se você apontar para um provedor real por engano.
Prefira um arquivo a exports no shell
A CLI carrega automaticamente o ./.env do diretório em que você a executa. Variáveis de
shell sempre vencem, então um .env é um padrão, não uma sobrescrita.
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o-mini
OPENAI_BASE_URL=https://api.openai.com/v1Copie o .env.example — ele é gerado a partir do registro de configurações, então lista
todas as variáveis que realmente existem, com seus padrões, e cada linha começa
comentada, de modo que copiá-lo é seguro.
Para vários ambientes, sobrescritas por comando e handbook.config.yaml, veja
Configuração.
Verifique a instalação
Dois comandos, nesta ordem.
1. A cadeia de ferramentas roda?
pnpm demoPipeline completo, offline, contra um projeto de exemplo embutido e um LLM simulado embutido. Se isso passar, sua instalação está em ordem.
2. Meu endpoint está acessível e configurado?
handbook config --command generateIsso imprime cada configuração, seu valor resolvido e de qual camada ele veio — flag, variável de ambiente, arquivo de configuração ou padrão. Segredos são mascarados.
handbook config --check # exit code 2 if anything is invalid or missingFaça isso antes de uma execução longa
Uma variável de ambiente com erro de digitação antes significava "rodou silenciosamente com o padrão". O
--check transforma isso em uma falha com a variável nomeada na mensagem — o que é muito mais barato de
descobrir agora do que quarenta minutos dentro de uma geração.
A seguir
O que é o Handbooks?
Um código-fonte entra, dois manuais saem — um site de documentação narrado que o seu time lê e um índice de localização com que o seu agente de código se orienta. Do mesmo mapa parseado, sempre em dia com o código.
Guia rápido
Execute a cadeia de ferramentas inteira, de ponta a ponta, em cerca de trinta segundos — offline, sem chave de API e sem gastar tokens.