リファレンス
パッケージ索引
11 個の npm パッケージ、それぞれが何を export するのか、そしてそのうちどれが LLM 無しでも動くのか。
Handbooks は 11 個のパッケージからなるモノレポです。そのうち 4 つは LLM に一切触れ ず、単体でも十分に役立ちます。
| パッケージ | 役割 | LLM? | ドキュメント |
|---|---|---|---|
@handbooks/core | データモデル、zod スキーマ、設定レジストリ、ユーティリティ | ❌ | README |
@handbooks/analyzer | 多言語対応の静的コールグラフ抽出 | ❌ | README |
@handbooks/llm | OpenAI 互換クライアント、キャッシュ、actor–critic、モック | ✅ | README |
@handbooks/pipeline | 生成パイプライン、phases 1–3 | ✅ | README |
@handbooks/renderer | Markdown、HTML、エージェント向けインデックス、llms.txt | ❌ | README |
@handbooks/skill | SKILL のパッケージング、検証、ドリフトハッシュ | ❌ | README |
@handbooks/planner | 読み取り専用のプランニングエージェント | ✅ | README |
@handbooks/patcher | バイト厳密な適用、バックアップ、ロールバック | ❌ | README |
@handbooks/resync | 差分ロールフォワード | ✅ | README |
@handbooks/studio | ローカル Web UI | ✅ | README |
@handbooks/cli | handbook コマンド | — | README |
単体でとくに役立つ 3 つ
@handbooks/analyzer — 18 言語ぶんのコールグラフ
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: '',
},
);LLM なし、ネットワークなし、ネイティブコンパイルなし。
@handbooks/patcher — 編集プランを安全に適用する
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 })
}プランの形式は適用とロールバックに記載しています。
プランが @handbooks/planner から来たものである必要はどこにもありません — 手で書い
ても構いません。
@handbooks/renderer — 任意の HandbookModel をレンダリングする
import { renderMarkdownHandbook, renderAgentSite, renderLlmsTxt } from '@handbooks/renderer';
renderMarkdownHandbook(model, 'out/');
renderAgentSite(model, 'out/agent');
renderLlmsTxt(model, 'out/');唯一の契約は HandbookModel です。好きなやり方で 1 つ埋めれば、レンダリングも
SKILL のパッケージングもプランニングも、すべて動きます。
主要な export を一目で
// @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 · JobRunnerインストール
pnpm add @handbooks/analyzer # or npm / yarnすべてのパッケージは ESM 専用（"type": "module"）で、型宣言を同梱し、Node ≥ 20.11
を要求し、MIT ライセンスです。サードパーティのバージョンはワークスペースの catalog
で一度だけピン留めされているので、2 つのパッケージが同じライブラリの別々のバージョ
ンに行き着くことはありえません。