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.

Guia do repositório

O que cada diretório de nível superior contém, onde cada responsabilidade fica dentro de server/, a ordem em que ler o código e as convenções sem as quais um pull request é reprovado.

Estrutura de nível superior

Caminho Conteúdo
server/ o servidor FastAPI: pacotes de domínio (memory, code, tracker, …), o registro de operações, workers, transportes, CLI, configurações
extractor/ o serviço extrator de referência (loom_extractor/): detecção de formato e os parsers de documentos, executados fora do servidor; sua imagem (Dockerfile, publicada como ghcr.io/clickhouse/loom-extractor) e seu lock (uv.lock); veja extração de documentos
sdk/python/ o SDK Python, publicado como clickhouse-loom (sdk/python/loom/)
sdk/typescript/ o SDK TypeScript, publicado como @clickhouse/loom (sdk/typescript/src/)
frontend/ o painel React servido em / (Vite + Tailwind); src/, specs do Playwright em e2e/, scripts/bundle_budget.mjs
schemas/ migrations/ (SQL numerado), schema.sql (formato atual gerado), otel/ (tabelas OTel do ClickStack), ops/ (SQL executado manualmente); veja schemas/README.md
dev/ stacks do compose, scripts de operação (loom_ingest.py, loom_init.py, onboard_tenant.py, backup e restauração, verify_audit_chain.py), ci_start_clickhouse.sh, redeploy_preflight.sh
deploy/ configuração do servidor ClickHouse (clickhouse-config/), o modelo Lemmagen3 (lemmagen3/), o proxy blue/green (proxy/), o chart Helm (helm/), o perfil AppArmor do sandbox de jobs de repositório (apparmor/), o template de env standalone (standalone/), o CronJob agendado de cópia de namespace (okf-sync/), painéis (dashboards/, hyperdx_dashboards.md, clickstack_sources.sh)
bench/ harnesses e gates de benchmark, seus fixtures (fixtures/), datasets, rubricas, avaliações de aceitação e de skills; veja benchmarks de desempenho
integrations/ integrações de clientes: os plugins do Claude Code e do Codex, os hooks do Cline, o grep shim, hooks do Cursor e de transcrição genéricos, o gate de CI do OKF
skills/ as Agent Skills independentes: loom-code e loom (o guia do agente que a imagem do servidor inclui e que mentor.guide serve)
scripts/ codegen/ (geradores), gates/ (ratchets e proteções de CI), ops/ (ferramentas de operação), scip_harness/ (produtores da camada do compilador), docs_site/ (o hook do site de documentação, a substituição de tema, o builder fixado e o envio ao IndexNow), i18n/ (o gerador de traduções e sua verificação de atualização)
tests/ unit/, integration/, analyzer/, code_lanes/, fixtures/ (abaixo)
examples/ exemplos de integração executáveis (claude_agent_loop.py, ledger_run.py, log_conversation.py, onboarding_walkthrough.py) e o starter de curso que um professor copia para um repositório próprio (course-starter/, ensino)
i18n/ traduções automáticas do README, do quickstart e das páginas de casos de uso, uma pasta por idioma em LANGUAGES; geradas por scripts/i18n/translate.py (.github/workflows/i18n.yml), nunca editadas manualmente
docs/ esta documentação; mkdocs.yml e scripts/docs_site/ a compilam como o site de documentação (.github/workflows/docs-site.yml)
.github/ workflows de CI, release e varredura (workflows/), templates de issues e pull requests, e social-preview.png, a imagem enviada em Settings → General → Social preview (o GitHub lê apenas a cópia enviada)
.devcontainer/ o teste no GitHub Codespaces: um dev container que instala a última versão com o instalador e conecta o Claude Code; não é um ambiente de desenvolvimento (guia de início rápido)
Dockerfile, Makefile, redeploy.sh, pyproject.toml, uv.lock a imagem do servidor, o executor de tarefas, o script de deploy blue/green, o pacote do servidor e seu arquivo de lock
server.json, context7.json, CITATION.cff, gemini-extension.json, .claude-plugin/, .cursor-plugin/, plugin.json, mcp.json, .agents/plugins/ a listagem no MCP Registry, a configuração do índice de documentação, a citação que o GitHub mostra como "Cite this repository", o manifesto da extensão do Gemini CLI, o marketplace do Claude Code com o manifesto da skill loom-code, o marketplace e plugin do Cursor, o pacote Agent Plugins que o GitHub Copilot CLI instala, o marketplace do Codex
llms-install.md os passos que um agente de código segue para instalar o Loom e adicioná-lo como servidor MCP
AGENTS.md, CLAUDE.md as instruções que todo agente de código lê; CLAUDE.md importa AGENTS.md
.claude/, .agents/skills/ as skills dos agentes, regras com escopo de caminho, o subagente revisor somente leitura e seu hook, e as configurações de permissão do projeto; .agents/skills/ vincula cada skill para o Codex

Dentro de server/

server/ é organizado por domínio. Uma requisição entra por um transporte, é despachada pelo registro de operações para um handler no app/ de um domínio, que executa a lógica pura de domain/ e lê e escreve por meio dos repositórios em store/, que guardam o SQL do domínio. O layout do servidor é o mapa completo, com as regras de importação que um teste de contrato impõe; o caminho da requisição está na visão geral do sistema.

Pacote / módulo Papel
memory/, code/, tracker/, knowledge/, erasure/, tasks/, identity/, insights/ os pacotes de domínio; cada um contém até cinco camadas: api/ (modelos de wire models*.py e listas de Operation em ops*.py), app/ (handlers e orquestração), domain/ (lógica pura), store/ (repositórios ClickHouse e construtores de linhas; memory/store/rows.py contém os construtores de linhas de versão), workers/ (loops em segundo plano)
operations/ o núcleo do registro: Operation e Role (base.py); registry.py importa o grupo de operações de cada domínio e monta ALL_OPERATIONS e OPERATIONS_BY_NAME; toolsets.py, projeção de leitura, o censo de alcance
transport/ HTTP (http.py) e MCP (mcp.py com mcp_schemas, mcp_config, mcp_tools, mcp_identity), feedback de argumentos, limites de corpo
workers/ o registro de workers (registry.py, _WORKERS) e o supervisor (supervisor.py) que o executa; cada loop fica no workers/ do seu domínio
settings/ todas as configurações em catalog.py, uma seção por área, compostas em Settings
auth/ emissão e verificação de JWT, papéis e concessões, login, OIDC, autocadastro, revogação
embedding/, llm/ superfícies de provedores plugáveis (OpenAI, Anthropic, Gemini, local, fake), caches e fallback
observability/ o emissor do ledger, log de auditoria, contabilização de custos e orçamentos, métricas e spans OTel, a lista problems que /v1/health reporta
clients/ clientes HTTP para serviços externos (o pool compartilhado de provedores, GitHub)
storage/ composição de TTL por tabela
cli/ a árvore de comandos loom (app.py a monta)
main.py, boot.py, health.py, wiring.py o app FastAPI e seu lifespan (workers, transportes), as etapas de boot e desligamento (migração no boot, snapshot de revogação), /v1/health e wire()
core/ch.py o cliente ClickHouse, pooling e atribuição de queries (set_query_tag)
core/errors.py erros tipados (subclasses de LoomServerError) e seu status HTTP
core/ratelimit.py, core/ratelimit_shared.py, core/idempotency.py, memory/app/blacklist_guard.py proteções do caminho da requisição
core/schema/ o executor de migrações (migrate.py) e seu lock entre contêineres (migrate_lease.py), e as reescritas de schema que o executor e as ferramentas de rebuild compartilham (table_rebuild.py, vector_codec_ddl.py)

Dentro de tests/

Caminho Conteúdo
tests/unit/ testes rápidos que não precisam de ClickHouse; snapshots/ (árvore e ajuda da CLI, registro de workers, API pública do SDK), fixtures/, helpers compartilhados
tests/integration/ testes contra um servidor em execução e o ClickHouse (tests/conftest.py e tests/integration/conftest.py fazem a ligação), incluindo a sonda de vazamento entre principals
tests/analyzer/ o corpus de instruções: os formatos de cada construtor de SQL passando por EXPLAIN QUERY TREE em tabelas vazias migradas; veja o README
tests/code_lanes/ o corpus das lanes de SQL e shell: o que o índice de código deriva de tests/fixtures/code_lanes/, comparado com uma expectativa commitada
tests/fixtures/ entradas compartilhadas entre as suítes

Como cada suíte é executada, ignorada e usada como critério no CI está em testes.

Ordem de leitura para quem está começando a contribuir

  1. O README e a visão geral do sistema: a superfície do produto e o formato do sistema.
  2. server/operations/registry.py: o registro de wire-ops que todo transporte percorre.
  3. server/main.py, o lifespan: como as migrações, os workers e os transportes são conectados.
  4. O grupo de ops em server/<domain>/api/ops*.py referente ao que você está alterando, depois o handler correspondente em server/<domain>/app/ e os repositórios em server/<domain>/store/ que ele chama.
  5. schemas/schema.sql para as tabelas que ele lê e escreve.
  6. AGENTS.md e .claude/rules/: as convenções e suas justificativas.

Convenções que não são óbvias

O CONTRIBUTING.md as lista, e o AGENTS.md, junto com as regras em .claude/rules/, explica os motivos. Estes testes e verificações as fazem valer:

Verificação Garante
tabelas de SDK geradas, censo de alcance (geração de código) ops são linhas do registro
tests/integration/test_cross_principal_leakage.py ops de id em toda a organização ocultam uma linha de outro principal como found=False
test_memory_versions_schema.py as colunas de loom.memory são espelhadas em loom.memory_versions
test_migrations_additive.py, o checksum do ledger (migrações) migrações são aditivas e nunca são editadas
test_every_table_is_classified.py toda tabela é classificada para apagamento
test_settings_attribute_access.py, test_settings_reference.py configurações são lidas como settings.<field>, e a referência está atualizada
test_worker_registry_snapshot.py, test_worker_registry_parity.py workers são linhas do registro
ruff BLE001 um except genérico explica o motivo
scripts/gates/function_length_gate.py nenhuma função cresce além de sua linha de base
tests/unit/test_public_copy.py o texto do repositório é neutro quanto ao produto

Os formatos fundamentais (ClickHouse como único mecanismo, a tupla de identidade, a auditoria de hash de conteúdo por linha, as cinco operações de revisão de crenças) exigem uma justificativa de design no pull request e uma atualização da página de arquitetura correspondente (mudanças relevantes).

Relacionados