Pular para conteúdo

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