Установка

Требования

Это действительно весь список. Здесь нет шага нативной компиляции — языковые парсеры поставляются как WebAssembly, поэтому никакого node-gyp, никакого компиляторного тулчейна, никакого Python.

Вариант 1 — из клона репозитория (рекомендуется на этапе оценки)

git clone <this repo>
cd handbooks
pnpm install
pnpm build

Затем сделайте вызов CLI удобным:

alias handbook="node $(pwd)/packages/cli/dist/main.js"
handbook --help

Или вовсе пропустите алиас и используйте pnpm-шорткаты, которые сначала выполняют инкрементальную сборку (около 0,4 с на прогретом кеше) и пробрасывают флаги напрямую:

pnpm analyze --source ~/code/myrepo --work work/myrepo
pnpm handbook --help

Вариант 2 — как глобальный CLI

npm i -g @handbooks/cli
handbook --help

Вариант 3 — Docker, совсем без локального Node

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 analyze

О Studio, окружениях и оговорке про доступ только с localhost см. руководство по Docker.

Вариант 4 — как библиотеки

Каждая возможность — это опубликованный пакет, который можно использовать отдельно. Анализатор, рендерер, упаковщик skill и патчер никогда не касаются LLM, поэтому работают автономно:

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 rollback

См. индекс пакетов.

Настройка конечной точки LLM

Phase 1 — статический анализ — никогда не требует ключа. Всё остальное требует.

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 endpoint

Предпочитайте файл экспортам в шелле

CLI автоматически загружает ./.env из каталога, в котором вы его запускаете. Переменные шелла всегда побеждают, так что .env — это значение по умолчанию, а не переопределение.

OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o-mini
OPENAI_BASE_URL=https://api.openai.com/v1

Скопируйте .env.example — он генерируется из реестра настроек, поэтому перечисляет каждую реально существующую переменную с её значением по умолчанию, и каждая строка изначально закомментирована, так что копировать его безопасно.

О нескольких окружениях, переопределениях для отдельных команд и handbook.config.yaml см. Конфигурацию.

Проверка установки

Две команды, именно в этом порядке.

1. Запускается ли тулчейн вообще?

pnpm demo

Полный конвейер, офлайн, на встроенном образце проекта и встроенном mock-LLM. Если это проходит, с вашей установкой всё в порядке.

2. Доступна ли и настроена ли моя конечная точка?

handbook config --command generate

Эта команда печатает каждую настройку, её итоговое значение и из какого слоя оно пришло — флаг, переменная окружения, файл конфигурации или значение по умолчанию. Секреты маскируются.

handbook config --check    # exit code 2 if anything is invalid or missing

Дальше