Справочник конфигурации

Эта страница — перевод сгенерированной страницы. Английский оригинал генерируется командой pnpm run config:docs из реестра настроек и защищён тестом на дрейф; перевод поддерживается вручную — когда меняется оригинал, обновите и его.

Приоритет

Каждая настройка разрешается через одни и те же слои, в порядке убывания приоритета: флаг > окружение шелла > .env > handbook.config.yaml > значение по умолчанию. Побеждает первый слой, который даёт значение, и все нижележащие слои для этой настройки игнорируются. Запустите handbook config — или handbook config --command <name>, чтобы увидеть только одну подкоманду, — чтобы проверить, что на самом деле разрешилось и из какого слоя это пришло.

Именование

Один ключ key в camelCase из реестра управляет всеми тремя поверхностями сразу: флагом, переменной окружения и ключом в файле конфигурации. Префикс с именем команды у любой из них ограничивает эту поверхность одной подкомандой, и это одно и то же преобразование для всех трёх — HANDBOOK_<KEY> становится HANDBOOK_<COMMAND>_<KEY>, а key становится <command>Key, записан ли он плоско или вложенно на один уровень под <command>:. Настройка, помеченная ниже как (с областью видимости), принимает только префиксное имя переменной окружения, потому что её смысл меняется от команды к команде (--out, --lang в пакете skill).

Начальная загрузка

Три настройки верхнего уровня указывают на слои выше и сами находятся вне реестра, разрешаясь один раз до всех остальных настроек — именно поэтому ни одну из них нельзя задать тем, что она загружает: ключ --env внутри handbook.config.yaml, строка --env-file внутри .env или ключ --config внутри того же файла остались бы просто некому прочитать.

• --env <name> (или HANDBOOK_ENV) выбирает каскад для конкретного окружения — единственная из трёх, у которой есть и флаг, и форма переменной окружения, поскольку она называет окружение, а не указывает на один конкретный файл.
• --env-file <path> загружает ровно этот один файл, минуя каскад ниже.
• --config <path> называет один конкретный файл конфигурации, минуя поиск с учётом окружения, описанный ниже (по умолчанию: ближайший файл семейства handbook.config.yaml, найденный подъёмом вверх от рабочей директории с остановкой на границе репозитория).

Каскад .env

Без --env-file CLI загружает каскад файлов .env* вместо одного фиксированного файла, в порядке убывания приоритета. Существующее правило applyEnvFile — никогда не перекрывать уже заданный ключ — это и есть то, что превращает каскад просто в «вызови их в таком порядке, побеждает первый файл, задавший ключ»:

Строки 2 и 3 применяются только тогда, когда --env/HANDBOOK_ENV называет окружение. Если не задано ни то ни другое, загружаются только строки 4 и 5 — ровно то, что загружалось до появления этого каскада, поэтому существующая настройка без .env.local не увидит вообще никаких изменений.

Поиск файла конфигурации с окружением

Если не считать --config, поиск по-прежнему поднимается вверх от рабочей директории и останавливается на границе репозитория, но в каждой посещённой директории он теперь сначала проверяет handbook.config.<name>.{yaml,yml,json} (только когда окружение названо), а уже потом обычный handbook.config.yaml и прочие — поэтому именованный файл всегда побеждает обычный файл, лежащий в той же директории, даже если обычный файл есть на уровне, более близком к рабочей директории. Если окружение не названо, поиск не меняется.

Запустите handbook config, чтобы увидеть, какое окружение активно и какие именно файлы оно загрузило, в порядке приоритета — каскад поверх четырёх слоёв значений — это слишком много возможных источников, чтобы держать их в голове, а слой, который эта команда не может показать, ничем не отличается от слоя, который не работает.

Разобранный пример для readWorkers (флаг --read-workers <n>, по умолчанию 12):

Формы для файла конфигурации взаимозаменяемы: плоский readWorkers: ... и вложенный generate: { readWorkers: ... } означают одно и то же, потому что файл уплощается тем же camelCase-склеиванием, прежде чем его прочитают.

analyze

generate

render

skill

validate

plan

apply

rollback

resync

studio

config