Справочник
Указатель пакетов
Одиннадцать npm-пакетов, что экспортирует каждый и какие из них работают вообще без LLM.
Handbooks — это монорепозиторий из одиннадцати пакетов. Четыре из них никогда не обращаются к LLM и полезны совершенно самостоятельно.
| Пакет | Роль | LLM? | Документация |
|---|---|---|---|
@handbooks/core | Модель данных, zod-схемы, реестр конфигурации, утилиты | ❌ | README |
@handbooks/analyzer | Извлечение статического графа вызовов для многих языков | ❌ | README |
@handbooks/llm | OpenAI-совместимый клиент, кеш, актёр–критик, мок | ✅ | README |
@handbooks/pipeline | Конвейер генерации, фазы 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 | Локальный веб-интерфейс | ✅ | README |
@handbooks/cli | Команда handbook | — | README |
Три самых полезных сами по себе
@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 — единственный контракт. Заполните её как вам угодно, и рендеринг,
упаковка скилла и планирование заработают все сразу.
Ключевые экспорты одним взглядом
// @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. Версии сторонних библиотек зафиксированы один
раз в каталоге рабочего пространства, поэтому два пакета никогда не окажутся на двух
версиях одной и той же библиотеки.