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
- Añadir una operación: la op, el handler, las tablas del SDK
- Estilo de la documentación: qué páginas están generadas
- Pruebas