Рендеринг результатов
Markdown, HTML-сайт, одна самодостаточная страница, локаторный индекс для агентов и llms.txt — всё детерминировано и бесплатно для повторного запуска.
handbook render --work <workdir> [--title <t>] [--html] [--html-single] [--agent-site] [--llms-txt]Без LLM. Без сети. Детерминировано. Одна и та же модель на входе — байт-в-байт идентичные файлы на выходе, поэтому этой команде место в CI, на каждом коммите.
Пять результатов
Записывается всегда.
<out>/
overview.md system prose + a mermaid stage map + "see also" links
index.md every stage, nested by depth, a paragraph each
<stage-id>.md one page per content-bearing stage
register.md the cross-stage state table (only when registers exist)Страница этапа содержит сводку этапа, ссылки на под-этапы, затем его файлы — сгруппированные и упорядоченные так, как решила phase 2c, каждый в виде карточки файла: назначение, роль, жизненный цикл, факты о вызовах и заметки по функциям для глубоких карточек.
Два поведения, о которых стоит знать:
- Устаревшие страницы вычищаются. Идентификаторы этапов меняются между генерациями; каждый рендер сначала удаляет страницы предыдущего рендера, поэтому переименованный этап не оставляет страницу-призрак, которую подберёт упаковщик скилла.
- Секция регистров на странице этапа идемпотентна — она добавляется под маркером и только тогда, когда маркера нет. Повторный рендеринг никогда не наслаивает дубликаты.
Ссылки на ваш исходный код
handbook render --work $WORK --source-base-url https://github.com/me/repo/blob/mainКаждый путь к файлу в handbook становится ссылкой на реальный файл. Направьте флаг на тег
или SHA коммита вместо main, если хотите, чтобы handbook ссылался на тот код, из
которого он был сгенерирован.
Без этого флага вывод вообще не содержит внешних URL — правильное умолчание для приватной кодовой базы.
Заголовки и языки
handbook render --work $WORK --title "Payments Service — Engineering Handbook"Язык повествования фиксируется во время генерации (--narrate-lang) и сохраняется в
phase3/narration.json. Рендерер читает его оттуда — каждая метка, заголовок и шапка
таблицы локализуются соответственно. Структура идентична на обоих языках, поэтому
инструментам, читающим вывод, не нужно знать, какой из них перед ними.
Повторный рендеринг как привычка
Рендеринг бесплатен и детерминирован, поэтому подключите его к CI:
- run: handbook render --work work/api --title "API Handbook" --html --agent-site --llms-txt
- run: handbook skill --handbook work/api/handbook --out skills/api --name api \
--work work/api --source . --agent-dir work/api/handbook/agent
- run: handbook validate --skill skills/api --source .См. Интеграция с CI.
Публикация HTML-сайта
Вывод — статический каталог с относительными ссылками и без внешних ресурсов, так что подойдёт любой статический хостинг:
# GitHub Pages
cp -R work/api/handbook/html/* docs-site/ && git add docs-site
# Netlify / Vercel / S3 / nginx
npx serve work/api/handbook/htmlРаздавайте llms.txt из корня сайта, чтобы агенты могли его найти.