Estender o Loom
Estender o Loom
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.
O Loom tem um registro para cada tipo de coisa: operações, workers, configurações, provedores, lanes de linguagem, etapas de extração e fontes de tracker. Para estender o Loom, adicione uma linha ao registro certo; HTTP, MCP, os SDKs e a referência gerada acompanham.
Verifique primeiro se apenas dados resolvem. Uma fonte de tracker, um esquema de registro, um procedimento ou uma política de histórico são configurados, não programados.
Escolha o ponto de extensão
| Você quer… | Ponto de extensão | Onde | Guia |
|---|---|---|---|
| Expor uma nova capacidade para os chamadores | Uma operação | server/<domain>/api/ops_<group>.py, server/<domain>/app/<group>.py |
Adicionar uma operação |
| Executar trabalho em segundo plano de forma agendada | Um worker | server/<domain>/workers/<name>.py, uma linha em server/workers/registry.py |
Adicionar um worker |
| Armazenar algo novo | Uma tabela ou coluna | schemas/migrations/<NNN>_*.sql, server/<domain>/store/ |
Adicionar uma tabela |
| Indexar uma nova linguagem de programação | Uma faixa de linguagem do índice de código | server/code/domain/extract/lang_<lang>.py, lang_detect.py, server/code/app/index/ingest.py |
Adicionar suporte a uma linguagem |
| Mudar o que a extração mantém para alguns chamadores | Uma etapa do pipeline | register_step em server/memory/app/pipeline.py |
Pipeline de extração |
| Ler um novo issue tracker ou histórico de CI | Uma fonte de tracker (somente dados) | tracker.source.add + tracker.source.set_mapping |
Contrato de registros do tracker |
| Guardar fatos com identidade e campos tipados | Um esquema de registro (somente dados) | memory_schema.register, memory.record.write |
Escrita de memória |
| Restringir o que os agentes podem fazer com base no histórico | Uma política de histórico (somente dados) | policy.set |
Tokens e grants |
| Usar outro provedor de embedding ou de LLM | Um cliente de provedor | server/embedding/, server/llm/ |
abaixo |
| Adicionar uma configuração | Um campo de configuração | A seção da área em server/settings/catalog.py |
abaixo |
| Capturar sessões de outro cliente, ou distribuir orientações para agentes | Uma integração, hook ou skill | integrations/, skills/ |
abaixo |
O que toda extensão compartilha
- O código é o registro. Os transportes iteram
ALL_OPERATIONS, o supervisor itera_WORKERSe a referência de configurações é gerada a partir deserver/settings/. Cada registro tem um teste de snapshot ou de censo que falha até você regenerá-lo. - Arquivos gerados.
make lintexecuta cada gerador com--check: as tabelas de operações do SDK (scripts/codegen/sdk_py_gen.py,sdk_ts_gen.py), o manifesto de alcance (op_reach_census.py), as páginas de referência (docs_reference.py,settings_reference.py) e as cópias do plugin do Codex (agent_plugin_sync.py). Veja geração de código. - Maturidade. Uma nova op declara
maturity="experimental", a menos que substitua uma op estável (adicionando uma operação). - Medição. Uma mudança no ranking, na extração ou em um padrão de provider executa o benchmark relevante antes e depois (ajuste de desempenho).
- Formas fundamentais não são pontos de extensão. O engine (ClickHouse), a tupla de identidade, a auditoria de hash de conteúdo por linha e as cinco operações de revisão de crenças só mudam com uma justificativa de design no PR e na documentação de arquitetura (visão geral do sistema).
Adicionar um provedor
Embedders e LLMs são clientes escolhidos por configurações.
Um embedder fica em server/embedding/, ao lado de openai.py, gemini.py, local.py e fake.py. Ele compartilha a infraestrutura HTTP de server/embedding/_provider.py:
- novas tentativas apenas em status que permitem repetição, três tentativas;
EmbedderInputTooLargeem vez de um truncamento silencioso pelo provedor;MalformedEmbeddingpara um vetor vazio, com largura errada ou não finito.
Conecte-o em server/embedding/embedder.py: a inferência do provedor a partir de LOOM_EMBEDDING_MODEL (_inferred_provider), os valores de LOOM_EMBEDDING_PROVIDER e as variáveis de chave em KEY_ENVS. Se a chave estiver ausente, o Loom recorre ao embedder fake e registra um erro no log.
Um LLM fica em server/llm/, ao lado de openai.py, anthropic.py e fake.py, e implementa LLMClient (server/llm/client.py). Conecte-o em _build_llm_client e em DEFAULT_MODEL_BY_PROVIDER, KEY_ENV_BY_PROVIDER e resolve_llm_provider (server/core/llm_provider.py).
Aviso: um provedor altera a qualidade. Os limiares de similaridade são calibrados para
text-embedding-3-small. Executemake bench-quickcom um novo provedor antes de torná-lo o padrão. Um novo embedder exigeloom reembedem cada namespace existente.
Adicionar uma configuração
Um novo campo vai na seção da sua área em server/settings/catalog.py (MemorySearch, Code, Tracker, …), o único arquivo em que toda configuração é declarada. O comentário acima dele diz o que ele controla e o que seus valores significam; esse comentário vira a linha correspondente na referência de configuração gerada. O nome da variável de ambiente é LOOM_<FIELD>.
Leia-o como settings.<field>, nunca como getattr(settings, "<field>", default). O tests/unit/test_settings_attribute_access.py falha no segundo caso: um valor padrão copiado acaba divergindo e esconde o ponto de leitura de quem remove o campo. Regenere com python scripts/codegen/settings_reference.py e python scripts/codegen/settings_schema.py.
Para aposentar uma flag, exclua a configuração, o seu branch e qualquer campo por requisição que a carregava. Um cliente que ainda envie o campo continua sendo atendido, com o campo listado em ignored_args.
Adicionar uma integração
| Integração | Onde | Notas |
|---|---|---|
| Um hook ou skill de plugin de agente de código | integrations/claude-code-plugin/ (hooks/, lib/, skills/) |
A fonte de verdade; python scripts/codegen/agent_plugin_sync.py copia scripts, skills e o ícone da listagem (assets/) para integrations/codex-plugin/. Conecte manualmente um novo hook ao hooks.json do Codex. Os clientes instalados recebem uma alteração quando a versão do plugin no manifesto muda. |
| Um hook de captura de sessão para outro cliente | integrations/<client>/ (cursor/, generic/) |
Chame loom ingest-transcript ou conversation.append, e memory.set_from_messages para a extração. |
| Uma skill de agente portátil | skills/<name>/SKILL.md |
Instalada pelo nome em qualquer cliente Agent-Skills; apenas orientação, sem hooks. |
| Um adaptador de framework | sdk/python/loom/integrations/, sdk/typescript/src/integrations/ |
Envolva o SDK na interface de store ou de memória do framework (LoomStore do LangGraph e LoomMemoryStore do Strands em Python, um adaptador do Strands em TypeScript). |
| Um backend de observabilidade | server/observability/ |
Os spans já carregam loom.request_id e são exportados por OTLP; prefira um coletor OTLP a um novo exportador. |
Integrações descreve as que já são distribuídas. Integração de agentes cobre o que qualquer novo cliente deve escrever e ler.