Referência de configuração

Esta página é a tradução de uma página gerada. O original em inglês é gerado por pnpm run config:docs a partir do registro de configurações e é protegido por um teste de deriva; esta tradução é mantida à mão — quando o original mudar, atualize-a também.

Precedência

Cada configuração é resolvida através das mesmas camadas, da maior prioridade para a menor: flag > env do shell > .env > handbook.config.yaml > padrão. A primeira camada que fornece um valor vence e todas as camadas abaixo dela são ignoradas para aquela configuração. Execute handbook config — ou handbook config --command <name> para ver apenas um subcomando — para verificar o que de fato foi resolvido e de qual camada veio.

Nomenclatura

Uma única key em camelCase no registro controla as três superfícies de uma vez: uma flag, uma variável de ambiente e uma chave de arquivo de configuração. Prefixar qualquer uma delas com o nome de um comando restringe aquela superfície a um único subcomando, e é a mesma transformação nas três — HANDBOOK_<KEY> vira HANDBOOK_<COMMAND>_<KEY>, e key vira <command>Key, seja escrita de forma plana ou aninhada um nível abaixo de <command>:. Uma configuração marcada como (com escopo) abaixo aceita apenas o nome de env prefixado, porque seu significado muda conforme o comando (--out, --lang no pacote skill).

Inicialização

Três configurações de nível superior apontam para as camadas acima e estão, elas próprias, fora do registro, sendo resolvidas uma única vez antes de qualquer outra configuração — que é também o motivo pelo qual nenhuma delas pode ser definida por aquilo que carregam: uma chave --env dentro de handbook.config.yaml, uma linha --env-file dentro de .env ou uma chave --config dentro desse mesmo arquivo não teriam mais ninguém para lê-las.

• --env <name> (ou HANDBOOK_ENV) seleciona uma cascata por ambiente — a única das três que tem tanto a forma de flag quanto a de variável de ambiente, já que nomeia um ambiente em vez de apontar para um arquivo exato.
• --env-file <path> carrega exatamente aquele único arquivo, contornando a cascata abaixo.
• --config <path> nomeia um arquivo de configuração exato, contornando a descoberta sensível ao ambiente descrita abaixo (padrão: o arquivo mais próximo da família handbook.config.yaml, encontrado subindo a partir do diretório de trabalho e parando na fronteira do repositório).

A cascata .env

Sem --env-file, a CLI carrega uma cascata de arquivos .env* em vez de um único arquivo fixo, da maior precedência para a menor. A regra existente de applyEnvFile — nunca sobrescrever uma chave já definida — é o que faz de uma cascata nada mais que "chame na ordem, o primeiro arquivo a definir uma chave vence":

As linhas 2 e 3 só se aplicam quando --env/HANDBOOK_ENV nomeia um ambiente. Sem nenhum dos dois definido, apenas as linhas 4 e 5 são carregadas — exatamente o que era carregado antes de esta cascata existir, de modo que uma instalação existente sem .env.local não vê mudança alguma.

Descoberta do arquivo de configuração com um ambiente

--config à parte, a descoberta continua subindo a partir do diretório de trabalho e parando na fronteira do repositório, mas em cada diretório visitado ela agora procura primeiro por handbook.config.<name>.{yaml,yml,json} (somente quando um ambiente é nomeado) antes do simples handbook.config.yaml e afins — de modo que um arquivo nomeado sempre vence um arquivo simples que esteja nesse mesmo diretório, mesmo quando existe um arquivo simples em um nível mais próximo do diretório de trabalho. Sem nenhum ambiente nomeado, a descoberta permanece inalterada.

Execute handbook config para ver qual ambiente está ativo e exatamente quais arquivos ele carregou, em ordem de precedência — uma cascata sobre quatro camadas de valores são fontes possíveis demais para acompanhar de memória, e uma camada que este comando não consegue mostrar não é diferente de uma camada que não funciona.

Exemplo prático para readWorkers (flag --read-workers <n>, padrão 12):

As formas do arquivo de configuração são intercambiáveis: um readWorkers: ... plano e um generate: { readWorkers: ... } aninhado significam a mesma coisa, porque o arquivo é achatado pela mesma junção camelCase antes de ser lido.

analyze

generate

render

skill

validate

plan

apply

rollback

resync

studio

config