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.
Layout do servidor
server/ é organizado por domínio. Cada plano do produto tem um único pacote que reúne suas declarações de protocolo, handlers, lógica pura, acesso ao ClickHouse e loops em segundo plano, e um teste fixa em que direção os imports podem apontar. Esta página é o mapa para decidir onde colocar um novo módulo e para interpretar um erro de import vindo do teste de contrato.
Pacotes
| Pacote | Responsável por | Pode importar |
|---|---|---|
server/main.py |
Montagem da aplicação: o lifespan, os routers, os workers, os transportes. Junto com server/boot.py, server/health.py, server/wiring.py, server/worker_main.py e server/__init__.py, os únicos módulos na raiz |
qualquer pacote |
server/boot.py |
Os passos de inicialização e encerramento do lifespan: a migração de boot serializada, as linhas de namespace do tracker do líder, o snapshot de revogação e o keyring, o loop de lease do supervisor, o write drain | qualquer pacote |
server/health.py |
GET /v1/health: a resposta de saúde em várias camadas (ClickHouse, provedores, o snapshot de boot, calibração, o limitador de taxa, e, sob demanda, os workers e a observabilidade) |
qualquer pacote |
server/wiring.py |
wire(): entrega a cada seam da plataforma a sua peça de domínio (o diretório de namespaces do gate de autenticação, os fatos dos medidores de estado); executado por main.py, pela CLI e pelas suítes de teste |
qualquer pacote |
server/worker_main.py |
A composition root do processo filho dos workers (python -m server.worker_main): o supervisor e o que seus workers usam, sem o lifespan de atendimento |
qualquer pacote |
server/core/ |
Infraestrutura transversal: o cliente do ClickHouse (ch), errors, orçamentos, datetimes, hashing, nomenclatura, cursores, idempotência, limites de taxa, política de armazenamento de vetores, schema/ (migrações e ferramentas de DDL) |
core, settings |
server/settings/ |
Todas as configurações declaradas em catalog.py, uma seção por área, compostas em Settings |
core, settings |
server/operations/ |
O núcleo do registro: Operation e Role (base.py), o registro achatado (registry.py: ALL_OPERATIONS, OPERATIONS_BY_NAME), toolsets.py, projeção de leitura, o censo de alcance |
core, pacotes da plataforma, o api de cada domínio |
server/transport/ |
HTTP e MCP: admissão, vinculação de requisições, listagens, o primer | core, pacotes da plataforma; o api, app e domain de um domínio (nunca o store ou workers); não cli |
server/cli/ |
O comando loom, um adaptador externo |
qualquer pacote |
server/workers/ |
O registro de workers (registry.py), o supervisor, o contexto de passagem, o status e seu store, o agendamento da primeira passagem, eventos de custo. Os loops dos workers ficam em seu domínio |
core, pacotes da plataforma; o workers de um domínio (as strings de módulo do registro) |
server/observability/ |
O ledger, eventos, linhas de auditoria, métricas, exportação de tracing | core, pacotes da plataforma |
server/auth/ |
Emissão e verificação de tokens, o gate de papel e namespace, a identidade por requisição | core, pacotes da plataforma |
server/embedding/, llm/ |
Provedores plugáveis de embedder e de LLM | core, pacotes da plataforma |
server/clients/, storage/ |
HTTP de saída (o pool compartilhado, GitHub); cláusulas de retenção | core, pacotes da plataforma |
server/memory/ |
O plano de memória: memory.*, busca, ask, extração, fatos, procedimentos, perfil, memória de trabalho, context packs, conflitos, blacklist, loom_search |
veja camadas |
server/code/ |
O plano de código: code.*, o índice (app/index/, domain/index/, store/index/), seus parsers (domain/extract/), os workers de ingestão e da camada do compilador |
veja camadas |
server/tracker/ |
Namespaces de tracker: tracker.*, verificações de duplicidade, os leitores de fontes ao vivo e seu cliente, as tabelas de tracker próprias do Loom |
veja camadas |
server/knowledge/ |
Documentos e chunks de conhecimento, conversas, documentos de repositório | veja camadas |
server/erasure/ |
A saga de apagamento, seu censo, os backends federados, o worker de recuperação | veja camadas |
server/tasks/ |
A caixa de entrada de tarefas, o ledger de execuções, seus loops de despertar e de webhook | veja camadas |
server/identity/ |
Namespaces, grants, política de histórico, escopo de leitura, acesso restrito, a página do painel e a API do chamador (/v1/me/*) |
veja camadas |
server/insights/ |
Superfícies do operador: ops.*, cost.*, agents.*, audit.list, ui.vitals, mentor.brief, as rotas /v1/admin/* |
veja camadas |
server/assistant/ |
O assistente: seu usuário de serviço do LibreChat e a definição do agente, configurados no boot | veja camadas |
Os pacotes da plataforma são core e os demais pacotes não pertencentes a domínios acima:
settings, operations, transport, cli, workers, observability, auth,
embedding, llm, clients e storage. Além de core e settings, cada um pode importar
qualquer outro pacote da plataforma, e nenhum importa um pacote de domínio, exceto conforme
indicado na tabela.
Camadas
Um pacote de domínio tem até cinco subpacotes. Um módulo vai para onde está sua responsabilidade principal; um domínio pequeno tem menos subpacotes.
| Camada | Contém | Pode importar |
|---|---|---|
api/ |
A interface externa: os modelos Pydantic de entrada e saída (models*.py) e as declarações Operation dos grupos de ops do domínio (ops*.py) |
core, operations, settings; o domain e o api de qualquer domínio; seu próprio app, para o handler ao qual uma Operation se vincula |
app/ |
Handlers e orquestração: o que uma op ou uma passada de worker faz, em ordem, com I/O | seu próprio api, app, domain, store; o app, o domain e os modelos de interface de outros domínios (api/models*.py); core e todos os pacotes de plataforma, exceto transport e cli |
domain/ |
Lógica pura, valores tipados e políticas: sem ClickHouse, sem rede | core (não seus módulos de I/O: ch, schema, idempotency, ratelimit_shared, namespace_write_marks), settings, o domain de qualquer domínio |
store/ |
Repositórios do ClickHouse e construtores de linhas: toda instrução que o domínio executa contra suas tabelas | core, settings, observability, storage, seu próprio store, o domain de qualquer domínio |
workers/ |
Loops em segundo plano, um módulo por linha do registro | como app, com workers no lugar de api; o app, o domain e os modelos de interface de outros domínios |
Um módulo de domain/ inicia um processo: server/code/domain/extract/bounded_parse.py, que
todo parser tree-sitter em domain/ chama, analisa cada fonte primeiro em um processo
filho local, sob limites de recursos.
Duas dependências estão ausentes de propósito. store/ nunca chama app/: um repositório
recebe valores e devolve linhas, de modo que um app pode ser testado com um store falso. E
nenhum domínio lê o store/ de outro domínio: ele chama o app/ desse domínio ou lê seus
tipos de domain/, de modo que o dono de uma tabela é o único autor de suas instruções.
Para chamar o handler de outro domínio, app/ e workers/ podem importar os modelos de
interface desse domínio (api/models*.py), nunca seu api/ops*.py. app/ importa os
modelos de interface, nunca os módulos ops, para que as declarações Operation possam
vincular handlers sem um ciclo de importação.
O contrato de imports
tests/unit/test_package_contracts.py analisa cada módulo em server/ com ast e classifica cada import (de nível superior, aninhado em if/try, dentro de uma função ou sob TYPE_CHECKING) pelo pacote e pela camada de ambas as pontas. Um import que as regras acima não permitem faz o teste falhar, informando o módulo que importa e o módulo importado.
Os imports que quebram o contrato hoje estão listados em tests/unit/package_contract_allowlist.txt, na forma importer -> imported pelo caminho do módulo. A lista só diminui: um par permitido que deixou de ocorrer também faz o teste falhar, então corrigir um import significa apagar a linha correspondente.
Uma segunda verificação roda ao lado: somente server/transport/, server/cli/ e server/main.py importam server.transport (tests/unit/test_transport_layering.py). Nenhum módulo de domínio importa server.cli.
Adicionando um módulo
- Escolha o domínio cuja tabela, grupo de ops ou plano o módulo atende. Um módulo que
atende todos os planos (um helper de ClickHouse, uma regra de hashing) fica em
core/; um que atende dois domínios fica naquele cujas linhas ele lê, e o outro o chama. - Escolha a camada pelo que o módulo faz, não por quem o chama: I/O ou um
async defque aguarda algo vai emapp/oustore/; uma função dos seus argumentos vai emdomain/. - Nomeie-o pelo que ele contém dentro do seu pacote, sem repetir o caminho:
server/erasure/app/saga.py, nãoserver/erasure/app/erasure_saga.py. - O
__init__.pyde um pacote contém uma docstring de uma linha dizendo o que o pacote possui. Ele só reexporta nomes quando é a superfície pública do pacote (server/memory/store/,server/code/store/index/). - Um loop em segundo plano é um módulo em
<domain>/workers/mais uma linha emserver/workers/registry.pycom o caminho completo do módulo. - Um alvo de mock ou monkeypatch, uma linha de registry e um piso de cobertura nomeiam módulos por caminho; escreva-os com o caminho real do módulo, nunca por meio de um reexport.
- Encontre os arquivos que o servidor distribui (migrations,
schema.sql, o build do frontend) por meio deserver.core.paths, nunca contando os pais de__file__(tests/unit/test_repo_paths.py).
Módulos do extrator
Os arquivos listados em extractor_stamp.STAGE_MODULES são o carimbo de versão do índice de código. O carimbo calcula o hash do nome de cada arquivo e dos seus tokens de código, e um import conta como os nomes que ele vincula, não como o pacote de onde vêm. Um carimbo alterado faz o índice de todo namespace de código ser derivado novamente. Esses arquivos ficam em server/code/domain/extract/, junto com extractor_stamp.py, que os lê do próprio diretório, e mantêm seus nomes de arquivo. Os módulos das linguagens ficam ao lado deles. Mover um deles entre pacotes não altera o carimbo; renomeá-lo, reformatá-lo (ruff format os exclui) ou mudar seu código altera.
Relacionados
- Visão geral do sistema — os componentes do plano de controle e o fluxo de requisições.
- Arquitetura do índice de código — o stamp do extrator e a reindexação.
- Caminho da requisição — o caminho que uma requisição percorre pelo transporte, pelo registro e por um handler.