Referencia de configuración

Esta página es la traducción de una página generada. El original en inglés lo genera pnpm run config:docs a partir del registro de ajustes y está protegido por una prueba de deriva; esta traducción se mantiene a mano: cuando cambie el original, actualízala también.

Precedencia

Cada ajuste se resuelve a través de las mismas capas, de mayor a menor prioridad: flag > shell env > .env > handbook.config.yaml > por defecto. Gana la primera capa que aporta un valor, y todas las capas por debajo se ignoran para ese ajuste. Ejecuta handbook config — o handbook config --command <name> para ver un único subcomando — para comprobar qué se resolvió realmente y de qué capa procede.

Nomenclatura

Una sola key en camelCase dentro del registro gobierna las tres superficies a la vez: un flag, una variable de entorno y una clave del archivo de configuración. Anteponer a cualquiera de ellas el nombre de un comando acota esa superficie a un único subcomando, y es la misma transformación en las tres — HANDBOOK_<KEY> pasa a ser HANDBOOK_<COMMAND>_<KEY>, y key pasa a ser <command>Key, tanto si se escribe de forma plana como anidada un nivel bajo <command>:. Un ajuste marcado como (acotado) más abajo solo acepta el nombre de variable de entorno con prefijo, porque su significado cambia según el comando (--out, --lang en el paquete skill).

Arranque

Tres ajustes de nivel superior apuntan a las capas anteriores y quedan ellos mismos fuera del registro, resueltos una sola vez antes que cualquier otro ajuste — que es también la razón por la que ninguno de ellos puede establecerse desde aquello que cargan: una clave --env dentro de handbook.config.yaml, una línea --env-file dentro de .env o una clave --config dentro de ese mismo archivo no tendrían ya nada que las leyera.

• --env <name> (o HANDBOOK_ENV) selecciona una cascada por entorno — el único de los tres con forma de flag y de variable de entorno a la vez, ya que nombra un entorno en lugar de apuntar a un archivo concreto.
• --env-file <path> carga exactamente ese archivo, saltándose la cascada de más abajo.
• --config <path> nombra un archivo de configuración concreto, saltándose el descubrimiento sensible al entorno de más abajo (por defecto: el archivo de la familia handbook.config.yaml más cercano, encontrado subiendo desde el directorio de trabajo actual y deteniéndose en el límite del repositorio).

La cascada de .env

Sin --env-file, la CLI carga una cascada de archivos .env* en lugar de un único archivo fijo, de mayor a menor precedencia. La regla ya existente de applyEnvFile — nunca sobrescribir una clave ya establecida — es lo que hace que una cascada no sea más que "llámalo en este orden; gana el primer archivo que establece una clave":

Las filas 2 y 3 solo se aplican cuando --env/HANDBOOK_ENV nombra un entorno. Sin ninguno de los dos establecido, solo se cargan las filas 4 y 5 — exactamente lo que se cargaba antes de que esta cascada existiera, de modo que una instalación existente sin .env.local no ve ningún cambio.

Descubrimiento del archivo de configuración con un entorno

--config aparte, el descubrimiento sigue subiendo desde el directorio de trabajo actual y deteniéndose en el límite del repositorio, pero en cada directorio visitado comprueba ahora primero si existe handbook.config.<name>.{yaml,yml,json} (solo cuando se nombra un entorno) antes que el handbook.config.yaml sin más y compañía — de modo que un archivo con nombre siempre gana a un archivo sin nombre situado en ese mismo directorio, incluso cuando existe un archivo sin nombre en un nivel más cercano al directorio de trabajo actual. Si no se nombra ningún entorno, el descubrimiento no cambia.

Ejecuta handbook config para ver qué entorno está activo y exactamente qué archivos cargó, en orden de precedencia — una cascada sobre cuatro capas de valores son demasiadas fuentes posibles como para seguirlas de memoria, y una capa que este comando no puede mostrar no se diferencia en nada de una capa que no funciona.

Ejemplo práctico para readWorkers (flag --read-workers <n>, valor por defecto 12):

Las formas del archivo de configuración son intercambiables: un readWorkers: ... plano y un generate: { readWorkers: ... } anidado significan lo mismo, porque el archivo se aplana con la misma unión camelCase antes de leerse.

analyze

generate

render

skill

validate

plan

apply

rollback

resync

studio

config