必要なのは Node 20.11 と pnpm、それだけです。ネイティブコンパイルも Python も node-gyp も不要 — パーサーは WebAssembly です。

要件


Node.js	≥ 20.11
pnpm	≥ 9
LLM エンドポイント	Phase 2 と 3 でのみ必要。OpenAI 互換なら何でも。

これで本当に全部です。ネイティブコンパイルの工程はありません — 言語パーサーは WebAssembly として同梱されるため、node-gyp も、コンパイラのツールチェーンも、 Python も不要です。

Node のバージョンは node --version で確認してください。nvm を使っているなら、リポジトリに .nvmrc が同梱されているので、nvm use で正しいバージョンが選ばれます。

方法 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

ショートカットが先にビルドする理由

すべての pnpm <command> は、CLI の前に tsc -b を実行します。これは、自分のコードをデバッグするのと、古くなった dist/ をデバッグするのとの分かれ目です — 後者は初めて起きたときに 1 時間を奪っていきます。

方法 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 — ライブラリとして

すべての機能は、単体で使える公開パッケージです。アナライザー、レンダラー、スキルパッケージャー、パッチャーは 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

ローカルおよびキー不要のエンドポイント

認証を行わないエンドポイント — vLLM、Ollama の OpenAI 互換シム、ローカルの LiteLLM — には OPENAI_API_KEY=EMPTY を使ってください。クライアントはそこに何かを必要とします。EMPTY は「意図的に無し」を伝える取り決めであり、誤って実在のプロバイダーに向けてしまったときも、紛らわしい 401 ではなく明確なエラーになります。

シェルの export よりもファイルを

CLI は、実行したディレクトリの ./.env を自動で読み込みます。シェル変数が常に勝つため、 .env はオーバーライドではなくデフォルトです。

.env

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

.env.example をコピーしてください — 設定レジストリから生成されているため、実在するすべての変数がデフォルト値付きで列挙されており、すべての行が最初からコメントアウトされているので、コピーしても安全です。

複数の環境、コマンドごとのオーバーライド、handbook.config.yaml については設定を参照してください。