Saltar a contenido

Las páginas sin traducir se abren en inglés y se indican como inglés.

Esta página es una traducción automática de la página en inglés, que prevalece. Machine-translated from the English page, which is authoritative.

Generación de código

Varios archivos del repositorio se derivan del código: las tablas de operaciones y los tipos de wire de los SDK, las páginas de referencia, las copias del plugin de Codex, el manifiesto de alcance de las operaciones (op reach manifest) y el volcado del esquema. Cada uno está commiteado, de modo que un lector lo ve sin ejecutar nada, y los generadores marcados a continuación tienen un modo --check que termina con código 1 cuando el archivo commiteado difiere de lo que escribiría el generador. make lint ejecuta cada una de esas comprobaciones, y CI las ejecuta en los jobs lint y sdk-typescript y en la suite de pruebas unitarias, de modo que un archivo desactualizado falla indicando en el mensaje el comando que hay que ejecutar.

Por qué commitear los archivos generados. Un archivo generado que solo se construye bajo demanda es invisible en la revisión: un cambio en el modelo de entrada de una operación cambiaría los tipos del SDK sin un diff que nadie lea. Commitearlos pone el efecto de un cambio junto al cambio, y la comprobación --check impide que ambos se desincronicen. El costo es un paso de regeneración en el cambio que modifica la fuente.

Los generadores

Todos viven en scripts/codegen/ y comparten scripts/codegen/common.py (la raíz del repositorio, los datos que una tabla del SDK incluye por op, el formato de ruff, la escritura atómica y el protocolo de escribir o comprobar).

Script Escribe A partir de --check en make lint
sdk_py_gen.py sdk/python/loom/ops.py: OpName, la tabla OPS (idempotencia, rol, madurez, presupuesto de latencia) y un TypedDict por cada modelo de entrada y de salida server.operations.registry.ALL_OPERATIONS sí
sdk_py_client_gen.py sdk/python/loom/client.py: OpsClient, un método por op (agent.client.tracker.source_add), con los tipos de los nombres de ops.py server.operations.registry.ALL_OPERATIONS sí
sdk_py_admin_gen.py sdk/python/loom/admin_routes.py: AdminRoutes, un método por ruta /v1/admin/* (agent.deployment.routes.settings_set) los routers /v1/admin/*: el método, la ruta, la puerta de acceso y el docstring de cada ruta sí
sdk_ts_gen.py sdk/typescript/src/generated/ops.ts: una interfaz por modelo, la tabla OPS y el tipo OpMap server.operations.registry.ALL_OPERATIONS (los JSON Schemas de los modelos) sí
agent_plugin_sync.py las copias del plugin de Codex de los scripts de hooks (hooks/*.mjs), la biblioteca compartida (lib/*.mjs), las skills y el icono del listado (assets/), idénticos byte a byte y con el bit de ejecución integrations/claude-code-plugin/ sí
settings_reference.py la referencia de configuración generada server/settings/catalog.py: la variable de entorno, el tipo, el valor por defecto y el comentario que precede a cada campo sí
settings_schema.py schemas/loom-settings.schema.json, el JSON Schema del archivo de settings en YAML los tipos, límites, valores por defecto y comentarios de los campos de settings, sin los secretos sí
settings_example.py loom.example.yaml, la plantilla del archivo de settings: todos los settings salvo los secretos, comentados en su valor por defecto bajo su descripción, por área los campos, valores por defecto, comentarios y marcas de live del catálogo de settings sí
docs_reference.py las regiones generadas de docs/reference/: operations, workers, cli, errors, schema, status_ops, status_switches, admin_routes (la tabla de rutas de operador) el registro, server/workers/registry.py (_WORKERS), tests/unit/snapshots/cli_tree.json, server/core/errors.py, schemas/schema.sql, server/settings/catalog.py, los routers /v1/admin/* sí
op_reach_census.py server/operations/reach_manifest.py (--write-manifest); en otro caso, una tabla de censo el registro y los toolsets de MCP sí
wire_changelog.py nada; imprime lo que cambió para los clientes entre dos revisiones el catálogo de capacidades construido en cada revisión no
gen_py_library_methods.py server/code/domain/extract/py_library_methods.py la biblioteca estándar del intérprete en ejecución no (depende del intérprete)
push_langfuse_prompts.py server/observability/langfuse_prompts.lock.json (--write) las constantes de prompts del servidor; las sube a Langfuse no

La referencia de configuración se genera a partir de comentarios, así que el comentario que precede a un setting es su documentación: edita el comentario, no la página. Las páginas de docs/reference/ son prosa escrita a mano alrededor de regiones <!-- BEGIN GENERATED: <name> --> … <!-- END GENERATED: <name> -->; solo se reescribe el texto entre un par de marcadores, de modo que una página puede explicar la tabla que contiene.

sdk_py_gen y sdk_ts_gen

El SDK de Python sigue siendo de diccionarios de entrada y de salida; el archivo generado añade los nombres, de modo que un editor autocompleta agent.call("memory.search", …) y un verificador de tipos ve los nombres de los campos sin una capa de modelos mantenida a mano. Los diccionarios son total=False, con Required[...] en los campos que el servidor exige. El generador de TypeScript convierte el JSON Schema de cada modelo en interfaces (los enums y consts pasan a uniones literales, anyOf a uniones, y los $defs compartidos se elevan una sola vez), de modo que client.call("memory.search", input) queda tipado de extremo a extremo. Ejecútalos tras cualquier cambio en el registro de una operación o en sus modelos:

python scripts/codegen/sdk_py_gen.py
python scripts/codegen/sdk_py_client_gen.py
python scripts/codegen/sdk_ts_gen.py

Ambos SDK exponen cada op como un método en el mismo lugar: el grupo es el primer segmento del nombre de la op y el método es el resto unido con ., en snake_case en Python (agent.client.tracker.source_add) y en camelCase en TypeScript (loom.tracker.sourceAdd). tests/unit/test_sdk_parity.py falla cuando las dos tablas de ops, o los dos nombres de método de cualquier op, difieren.

Sincronización de plugins de agentes

Los dos plugins de agentes de programación difieren solo en sus manifiestos y en la conexión de hooks (hooks/hooks.json). El plugin de Codex lleva copias en lugar de referencias ../, para que cada plugin sea un directorio autocontenido que un marketplace pueda descargar por sí solo. Tras añadir un script de hook o una skill al plugin de Claude Code, ejecuta la sincronización y haz commit de las copias; conecta un hook nuevo en el hooks.json de Codex a mano si Codex debe ejecutarlo.

Censo de alcance de las operaciones

Cada operación declara una madurez y debe tener una vía de acceso distinta de un POST HTTP directo, o estar declarada experimental. Los tipos de acceso (server/operations/reach.py, REACH_KINDS) son los listados de MCP (mcp_core, mcp_atomic, mcp_all, derivados en vivo de server/operations/toolsets.py), un método del SDK (sdk_method), un ejemplo incluido o un script de operador (sdk_example), un hook o integración de plugin (plugin_hook) y un punto de llamada del dashboard (dashboard). Los cuatro últimos salen de escanear el árbol, que un servidor desplegado no incluye, así que se confirman en el repositorio como reach_manifest.STATIC_REACH. --check hace cumplir la regla, que toda op sin punto de llamada del dashboard esté en server/operations/dashboard.py (con el motivo por el que no lo tiene), y que el manifiesto confirmado coincida con el árbol; --write-manifest lo actualiza. --call-counts --days 30 añade el número de llamadas de cada op desde loom.agent_events (el único modo que se conecta a ClickHouse), y --owners indica el commit que introdujo la declaración de cada op experimental.

Registro de cambios del protocolo

python scripts/codegen/wire_changelog.py <rev_a> <rev_b>           # markdown
python scripts/codegen/wire_changelog.py --since-hours 24 [rev_b]   # rev_a = rev_b's ancestor N hours back
python scripts/codegen/wire_changelog.py <rev_a> <rev_b> --json
python scripts/codegen/wire_changelog.py --snapshot <rev> > snap.json
python scripts/codegen/wire_changelog.py --diff a.json b.json

Materializa cada revisión con git archive, importa su registro en un intérprete hijo e imprime las operaciones y los campos de solicitud y respuesta añadidos o eliminados, además de los cambios de rol, presupuesto y nivel de MCP. Su salida va a las notas de la versión (proceso de publicación); la sección "what changed for clients" se genera, no se escribe.

Métodos de la biblioteca estándar de Python

El conjunto de nombres de métodos de la biblioteca estándar que usa el extractor de Python está fijado en el árbol para que una actualización del intérprete no pueda mover las aristas de llamadas. Regenerarlo cambia un módulo del extractor, lo que mueve el sello de versión del índice de código y vuelve a fragmentar cada espacio de nombres indexado; revisa el diff y regenéralo solo cuando sea lo que quieres.

Publicación de prompts en Langfuse

El servidor enlaza una generación de LLM con una versión de prompt de Langfuse buscando el hash de contenido del prompt en el lockfile confirmado, sin ninguna llamada en tiempo de ejecución. Sin --write el script planifica contra el lockfile sin conexión; --write sube los prompts cambiados (necesita LOOM_LANGFUSE_URL y LOOM_LANGFUSE_ADMIN_TOKEN) y reescribe el lockfile. Una prueba unitaria falla mientras al lockfile le falte un prompt registrado.

El volcado del esquema

schemas/schema.sql lo genera scripts/ops/dump_schema.py a partir de un ClickHouse con todas las migraciones aplicadas:

make schema-dump    # python -m scripts.ops.dump_schema
make schema-check   # --check: exit 1 with the head of the diff; writes nothing

Se describe en migraciones, ya que sigue cada cambio de migraciones y debe tomarse con la versión de ClickHouse que fija CI.

Snapshots que son pruebas, no generadores

La superficie de la CLI (tests/unit/snapshots/cli_tree.json, cli_help.json) y el registro de workers (tests/unit/snapshots/worker_registry.json) están fijados por pruebas unitarias, y se regeneran mediante una variable de entorno en la ejecución de las pruebas (pruebas). La referencia de la CLI se genera a partir de cli_tree.json, por lo que, tras regenerar el snapshot de la CLI, ejecuta también docs_reference.py.

Antes de hacer push

make lint            # every --check above, plus ruff, the gates and Biome's dashboard accessibility rules

Un fallo indica el script que hay que ejecutar; ejecútalo, revisa el diff y haz commit del archivo regenerado en el mismo cambio que su fuente.

Relacionado