Referencia de ajuste — variables de entorno

<!-- translations:start -->

English · 한국어 · 中文 · 日本語 · Русский · Español · Français · Deutsch

<!-- translations:end -->

Cada control que Tesserae lee del entorno, su valor por defecto y cuándo realmente querrías cambiarlo. Nada aquí es obligatorio: los valores por defecto se eligieron para que un simple tesserae compile funcione correctamente.

La configuración del proyecto y global (.tesserae/config.json, ~/.tesserae/config.json) tienen prioridad sobre la configuración del servidor LLM; las variables de entorno abajo anulan ambas para la ejecución donde estén establecidas.

Hooks que gastan dinero

Los hooks que el plugin Claude Code envía pueden lanzar una compilación en segundo plano. Cualquier cosa que gaste está desactivada por defecto:

export TESSERAE_HOOK_AUTOCOMPILE=1   # opt in a compilaciones automáticas

Bajo control: posttooluse-edit.sh (se ejecuta en cada Edit/Write) y session-end.sh. No bajo control, porque no cuestan nada: session-start.sh ejecuta tesserae code sync, que es determinístico, y pretooluse-compile.sh solo intercepta un tesserae compile que escribiste tú mismo.

Este defecto existe porque fue medido. Una base de conocimiento en ~/.tesserae hace que $HOME parezca la raíz del proyecto, y el resolver del hook caminaba hacia arriba desde el directorio de trabajo hacia el primer .tesserae/ que encontraba — así que cualquier sesión fuera de un proyecto registrado se resolvía en $HOME y compilaba el directorio de inicio completo: 15k archivos, un gráfico de 795 MB, ~10 horas de gasto en LLM, desde un proceso separado que sobrevivió a la sesión que lo inició.

resolve_project_root() ahora rechaza $HOME por cualquier ruta, y devuelve vacío en lugar de caer a la copia de seguridad del directorio de trabajo, así que los llamadores no-op en lugar de adivinar. Un hook que lanza trabajo del modelo debe activarse deliberadamente, no desactivarse después de que llegue la factura.

Extracción

TESSERAE_EXTRACT_TIMEOUT

Por defecto 1800 (segundos), por intento. Acota cada llamada de extracción codex/claude para que un proceso hijo bloqueado no pueda colgar la compilación.

Esto sucedió: una compilación se observó al 0% CPU durante 5 h 43 m con un proceso hijo codex exec inactivo durante 4 h 6 m, manteniendo .tesserae/compile.lock todo el tiempo. Ya había construido 32 resúmenes de comunidad en memoria pero nunca llegó a persistirlos.

Por intento, no por documento — al timeout el cliente rota a la siguiente carpeta de configuración CODEX_HOME / claude, así que el peor caso para un documento es timeout × perfiles configurados.

export TESSERAE_EXTRACT_TIMEOUT=3600   # más tiempo para documentos muy grandes
export TESSERAE_EXTRACT_TIMEOUT=0      # sin límite — ejecutar hasta completarse

Un valor que se establece pero no es utilizable (10m, 600s, negativo, inf) advierte en stderr y mantiene el valor por defecto. Un error tipográfico no debe desactivar silenciosamente una válvula de seguridad.

TESSERAE_EXTRACT_CONCURRENCY

Por defecto 4. Documentos extraídos en paralelo. Cada uno es un proceso hijo CLI bloqueante que toma aproximadamente un minuto, por lo que un bucle secuencial hace que el tiempo de reloj sea literalmente la suma de cada ida y vuelta del modelo — medido en ~2 h 40 m para 161 documentos.

El techo es el límite de velocidad de tu cuenta de proveedor, no tu máquina, por lo que el valor por defecto es modesto. Establece 1 para un comportamiento estrictamente secuencial.

La concurrencia nunca cambia el resultado: la lista de trabajo se fija en orden de ruta y los resultados se recopilan por índice, así que una ejecución en paralelo es byte-idéntica a una secuencial.

TESSERAE_LLM_CACHE

Por defecto activado. Caché de contenido direccionable de respuestas del proveedor CLI bajo ~/.tesserae/llm_cache, indexado por (documento, tipo, guía) más el modelo y esfuerzo de razonamiento — así que cambiar modelos re-pregunta en lugar de servir respuestas del modelo anterior. Solo se almacenan respuestas parseables, por lo que una generación deficiente no puede volverse permanente.

export TESSERAE_LLM_CACHE=0   # siempre re-preguntar

TESSERAE_LLM_CHUNK_CHARS

Caracteres por fragmento cuando un documento es demasiado grande para una llamada. Déjalo sin establecer a menos que estés alcanzando límites de contexto.

Servidor LLM

tesserae config status imprime el servidor resuelto y lo verifica para vivacidad.

Pasadas de compilación

Sobre resúmenes de comunidades: la pasada de compilación cubre ansiosamente el nivel más grueso; graph_map además materializa lazily un resumen la primera vez que desciendes a un alcance frío, almacenado en caché por nivel. Desactivar la pasada es una estrategia de costo legítima — solo pagas por ramas que realmente visitas — pero con una advertencia: la descención federada nunca materializa lazily. Las tarjetas de un proyecto hermano solo pueden nombrarse desde sus resúmenes en gráfico o cachés ya calientes, así que un proyecto en el que navegas entre proyectos quiere la pasada ansiosa activada.

Consulta y síntesis

Rutas e infraestructura

Recuperación de un corpus degradado

Cuando la extracción falla para un documento, se sirve por la línea base determinística y se marca en .tesserae/manifest.json. Sin la marca sería indistinguible de una extracción limpia, así que --changed-only lo saltaría para siempre y la degradación sería permanente hasta que el contenido del archivo cambiara.

tesserae compile --changed-only --retry-fallbacks

Reintenta solo los documentos marcados; los limpios permanecen saltados.

Inspeccionando la jerarquía

tesserae graph-map                          # mapa raíz
tesserae graph-map --scope <scope_id>       # descender
tesserae graph-map --scope '<alias>::'      # un proyecto hermano registrado

Cada tarjeta reporta size y leaf_member_count del archivo adjunto de jerarquía, más live_member_count — cuántos miembros el gráfico actual realmente lleva. Un 0 allí significa que el alcance está muerto (sesgo de archivo adjunto/gráfico): sáltalo en lugar de descender.

Agentes escriben en el gráfico

\graph_write\ (MCP) toma nodos y bordes tipados validados por esquema con proveniencia obligatoria, por lo que un agente registra un hallazgo como estructura en lugar de prosa que un extractor tiene que adivinar los tipos.

Rechaza en lugar de obligar: bordes sin tipo, tipos de nodo o borde fuera del vocabulario controlado, puntos finales pendientes y escrituras sin proveniencia se rechazan todas. Las escrituras duplicadas son idempotentes. Los nodos escritos por agentes sobreviven a una recompilación completa, \graph.json\ eliminado, \--limit\ y eliminación de corpus completo.

Verificar una reclamación contra el gráfico

\verify_claim\ (MCP) responde si el gráfico licencia un triple. Toma \(subject, predicate, object)\ — no hay parámetro de lenguaje natural, por diseño, porque un analizador hizo que la versión anterior respondiera SUPPORTED a la negación de un reclamo que apoyaba.

El veredicto es una función pura de bytes de gráfico: sin LLM, sin incrustación, sin coincidencia difusa en ningún lugar del camino de decisión.

Hay dos cosas que deliberadamente no hará. Nunca trata \supersedes\ como refutación — esa relación dice que un nodo fue reemplazado, no que un triple sea falso. Y una escritura de agente solo puede debilitar una clase de procedencia, nunca actualizar una, por lo que nada de lo que un agente afirma puede presentarse como fundamentado en documentos.

Vale la pena saber al leer resultados: en un gráfico real de 15.284 bordes, alrededor del 40% de los veredictos \SUPPORTED\ son tautológicos — bordes \evidenced_by\ cuyo intervalo citado es el objetivo del propio borde. Verdadero, pero no informativo.

Enrutamiento de una pregunta

\tesserae ask\ elige una ruta de recuperación por forma de pregunta: las búsquedas de entidad única van al backend económico, las preguntas multi-salto / "qué cambió" / "por qué" / amplitud del corpus van al gráfico. Los puntos de referencia independientes muestran que los gráficos están adelante en preguntas multi-salto, temporales y de síntesis, y atrás en búsqueda de hechos simples y costo — así que pagar precios de gráfico por cada pregunta es una pérdida.

La decisión aparece en el sobre devuelto, por lo que una respuesta económica es auditable. Anularlo con \--route\ en la CLI, o el parámetro \route\ en la herramienta MCP.