As páginas sem tradução abrem em inglês e são identificadas como inglês.
Esta página é uma tradução automática da página em inglês, que prevalece. Machine-translated from the English page, which is authoritative.
Geração de código
Vários arquivos do repositório são derivados do código: as tabelas de operações e os tipos de wire dos SDKs, as páginas de referência, as cópias do plugin do Codex, o manifesto de alcance das operações (op reach manifest) e o dump do schema. Cada um é commitado, de modo que o leitor o vê sem executar nada, e os geradores indicados abaixo têm um modo --check que sai com código 1 quando o arquivo commitado difere do que seria gerado. make lint executa cada uma dessas verificações, e o CI as executa nos jobs lint e sdk-typescript e na suíte de testes unitários, de modo que um arquivo desatualizado falha com o comando a executar indicado na mensagem de falha.
Por que commitar arquivos gerados. Um arquivo gerado que só é construído sob demanda fica invisível na revisão: uma mudança no modelo de entrada de uma operação alteraria os tipos do SDK sem um diff que alguém leia. Commitá-los coloca o efeito de uma mudança ao lado da própria mudança, e a verificação --check impede que os dois divirjam. O custo é uma etapa de regeneração na mudança que altera a fonte.
Os geradores
Todos ficam em scripts/codegen/ e compartilham
scripts/codegen/common.py (a raiz do repositório, os fatos que uma tabela de SDK carrega por op,
formatação com ruff, uma escrita atômica e o protocolo de escrever ou verificar).
| Script | Escreve | A partir de | --check em make lint |
|---|---|---|---|
sdk_py_gen.py |
sdk/python/loom/ops.py: OpName, a tabela OPS (idempotência, papel, maturidade, orçamento de latência) e um TypedDict por modelo de entrada e de saída |
server.operations.registry.ALL_OPERATIONS |
sim |
sdk_py_client_gen.py |
sdk/python/loom/client.py: OpsClient, um método por op (agent.client.tracker.source_add), tipado com os nomes de ops.py |
server.operations.registry.ALL_OPERATIONS |
sim |
sdk_py_admin_gen.py |
sdk/python/loom/admin_routes.py: AdminRoutes, um método por rota /v1/admin/* (agent.deployment.routes.settings_set) |
os routers /v1/admin/*: o método, o caminho, o controle de acesso e a docstring de cada rota |
sim |
sdk_ts_gen.py |
sdk/typescript/src/generated/ops.ts: uma interface por modelo, a tabela OPS, o tipo OpMap |
server.operations.registry.ALL_OPERATIONS (os JSON Schemas dos modelos) |
sim |
agent_plugin_sync.py |
as cópias do plugin do Codex dos scripts de hook (hooks/*.mjs), da biblioteca compartilhada (lib/*.mjs), das skills e do ícone da listagem (assets/), idênticas byte a byte, com o bit de execução |
integrations/claude-code-plugin/ |
sim |
settings_reference.py |
a referência de configuração gerada | server/settings/catalog.py: a variável de ambiente, o tipo, o valor padrão e o comentário acima de cada campo |
sim |
settings_schema.py |
schemas/loom-settings.schema.json, o JSON Schema do arquivo de configurações YAML |
os tipos, limites, valores padrão e comentários dos campos de configurações, sem os segredos | sim |
settings_example.py |
loom.example.yaml, o modelo do arquivo de configurações: todas as configurações exceto os segredos, comentadas no valor padrão sob sua descrição, por área |
os campos, valores padrão, comentários e marcas live do catálogo de configurações | sim |
docs_reference.py |
as regiões geradas de docs/reference/: operations, workers, cli, errors, schema, status_ops, status_switches, admin_routes (a tabela de rotas do operador) |
o registro, server/workers/registry.py (_WORKERS), tests/unit/snapshots/cli_tree.json, server/core/errors.py, schemas/schema.sql, server/settings/catalog.py, os routers /v1/admin/* |
sim |
op_reach_census.py |
server/operations/reach_manifest.py (--write-manifest); caso contrário, uma tabela de censo |
o registro e os toolsets do MCP | sim |
wire_changelog.py |
nada; imprime o que mudou para os clientes entre duas revisões | o catálogo de capacidades construído em cada revisão | não |
gen_py_library_methods.py |
server/code/domain/extract/py_library_methods.py |
a biblioteca padrão do interpretador em execução | não (depende do interpretador) |
push_langfuse_prompts.py |
server/observability/langfuse_prompts.lock.json (--write) |
as constantes de prompt no servidor; envia-as ao Langfuse | não |
A referência de configuração é renderizada a partir de comentários, então o comentário acima de uma configuração é
a sua documentação: edite o comentário, não a página. As páginas de docs/reference/ são
prosa escrita à mão em volta de regiões <!-- BEGIN GENERATED: <name> --> … <!-- END GENERATED: <name> -->;
só o texto entre um par de marcadores é reescrito, de modo que uma página pode explicar a
tabela que carrega.
sdk_py_gen e sdk_ts_gen
O SDK Python continua recebendo e devolvendo dicts; o arquivo gerado adiciona os nomes, de modo que um editor
completa agent.call("memory.search", …) e um verificador de tipos enxerga os nomes dos campos sem
uma camada de modelos mantida à mão. Os dicts são total=False, com Required[...] nos campos que o
servidor exige. O gerador de TypeScript transforma o JSON Schema de cada modelo em interfaces
(enums e consts viram uniões de literais, anyOf vira união, os $defs compartilhados são extraídos uma única vez), de modo que
client.call("memory.search", input) é tipado de ponta a ponta. Execute-os após qualquer mudança no
registro de uma operação ou em seus modelos:
python scripts/codegen/sdk_py_gen.py
python scripts/codegen/sdk_py_client_gen.py
python scripts/codegen/sdk_ts_gen.py
Os dois SDKs expõem cada op como um método no mesmo lugar: o grupo é o primeiro segmento do nome da op,
o método é o restante unido por ., em snake_case no Python
(agent.client.tracker.source_add) e em camelCase no TypeScript (loom.tracker.sourceAdd).
tests/unit/test_sdk_parity.py falha quando as duas tabelas de ops, ou os dois nomes de método de
qualquer op, divergem.
Sincronização dos plugins de agente
Os dois plugins de agentes de código diferem apenas em seus manifestos e na ligação dos hooks
(hooks/hooks.json). O plugin do Codex carrega cópias em vez de referências ../, para que cada
plugin seja um diretório autocontido que um marketplace possa baixar sozinho. Depois de adicionar um
script de hook ou uma skill ao plugin do Claude Code, execute a sincronização e faça commit das cópias; ligue
um novo hook ao hooks.json do Codex à mão se o Codex deve executá-lo.
Censo de alcance das ops
Toda operação declara uma maturidade e precisa ter um caminho de alcance além de um POST HTTP
bruto, ou ser declarada experimental. Os tipos de alcance (server/operations/reach.py,
REACH_KINDS) são as listagens do MCP (mcp_core, mcp_atomic, mcp_all, derivadas ao vivo
de server/operations/toolsets.py), um método de SDK (sdk_method), um exemplo distribuído ou
script de operador (sdk_example), um hook de plugin ou integração (plugin_hook) e um ponto de chamada
do painel (dashboard). Os quatro últimos vêm da varredura da árvore, que um servidor implantado não carrega, então são commitados como reach_manifest.STATIC_REACH.
--check garante a regra, que toda op sem ponto de chamada no painel está em
server/operations/dashboard.py (com o motivo de não estar), e que o manifesto commitado
corresponde à árvore; --write-manifest o atualiza. --call-counts --days 30 adiciona
a contagem de chamadas de cada op a partir de loom.agent_events (o único modo que se conecta ao ClickHouse),
e --owners indica o commit que introduziu a declaração de cada op experimental.
Changelog do 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
Ele materializa cada revisão com git archive, importa seu registro em um interpretador
filho e imprime as operações e os campos de requisição e resposta adicionados ou
removidos, além de mudanças de papel, orçamento e camada do MCP. Sua saída vai para as notas de versão
(processo de release); a seção "o que mudou para os clientes"
é gerada, não escrita.
Métodos da biblioteca Python
O conjunto de nomes de métodos da biblioteca padrão que o extrator Python usa fica congelado na árvore, para que uma atualização do interpretador não mova as arestas de chamada. Regenerá-lo altera um módulo do extrator, o que move o carimbo de versão do índice de código e refaz os chunks de todo namespace indexado; revise o diff e regenere somente quando for essa a intenção.
Envio de prompts ao Langfuse
O servidor vincula uma geração de LLM a uma versão de prompt do Langfuse buscando o hash de conteúdo
do prompt no lockfile commitado, sem nenhuma chamada em tempo de execução. Sem --write,
o script planeja contra o lockfile offline; --write envia os prompts alterados (exige
LOOM_LANGFUSE_URL e LOOM_LANGFUSE_ADMIN_TOKEN) e reescreve o lockfile. Um teste
unitário falha enquanto o lockfile não tiver um prompt registrado.
O dump do schema
schemas/schema.sql é gerado por scripts/ops/dump_schema.py a partir de um ClickHouse com
todas as migrations aplicadas:
make schema-dump # python -m scripts.ops.dump_schema
make schema-check # --check: exit 1 with the head of the diff; writes nothing
Ele é abordado em migrações, pois acompanha cada alteração de migration e deve ser gerado com a versão do ClickHouse fixada pelo CI.
Snapshots que são testes, não geradores
A superfície da CLI (tests/unit/snapshots/cli_tree.json, cli_help.json) e o registro de workers (tests/unit/snapshots/worker_registry.json) são fixados por testes unitários e regenerados por uma variável de ambiente na execução dos testes
(testes). A referência da CLI é renderizada a partir de cli_tree.json, então, depois de regenerar o snapshot da CLI, execute também docs_reference.py.
Antes de fazer o push
make lint # every --check above, plus ruff, the gates and Biome's dashboard accessibility rules
Quando houver uma falha, a mensagem indica o script a executar; execute-o, revise o diff e faça o commit do arquivo regenerado na mesma mudança que contém a sua fonte.
Relacionados
- Adicionando uma operação: a op, o handler, as tabelas do SDK
- Estilo da documentação: quais páginas são geradas
- Testes