3.0.0
Contexto pela tarefa
atlas_context reúne o pacote de um símbolo ou arquivo para editar, depurar, revisar ou entender. affected mostra o alcance de uma mudança no grafo.
RELEASE NOTES VERSÃO 3.0.0 / 15 OUT 2026
O contexto
evoluiu.
Do trecho de código ao contexto da decisão.
Conheça o que muda no Atlas 3.0 e prepare seu projeto para a versão 3.0.0.
CODESTEER ATLAS
3.0
2.1.1→3.0.0
INDEX FORMAT 2.3.0
LANÇAMENTO · 15 OUT 2026
A versão 3.0.0 está preparada para lançamento em 15/10/2026, com Jev v2, contexto compacto e expansão seletiva. Instale pela main depois do merge da PR; até lá, use o snapshot fixo abaixo.
01 / O QUE CHEGOU
Mais evidência.
Menos contexto desperdiçado.
Busca local continua sendo a base. As novas camadas acrescentam contexto, atualização e controle sobre o que chega ao agente.
3.0.0
A história junto do código
Mensagens de commits locais entram na busca. O modo debug inclui histórico recente ligado ao alvo. Até 100 commits por arquivo e 24 meses, sem flag nova.
V3.0 · OPT-IN
Jev com rubrica v2
Já implementado na branch v3.0, o modelo System One da TypeSafe usa a rubrica v2 por padrão quando habilitado e julga os candidatos recuperados localmente. Refina a ordem e, no compacto, pode remover o que pouco ajuda à pergunta.
Entender e configurar ↗V3.0 · OPT-IN
Abra só o que falta
Perfil compacto, deduplicação e orçamento menor. atlas_expand recupera o original por referência; classes grandes abrem com cabeçalho e outline de métodos.
2.2.0 · OPT-IN
Um índice mais vivo
Watcher atualiza após salvar. SCIP acrescenta chamadas com precisão do toolchain. Imports de mais linguagens e cobertura declarada mostram os limites do grafo.
Ativar por necessidade ↗3.0.0 · OPT-IN
Propósito por símbolo
A camada semântica gera descrições e sumários em semantic.json. Prefere sampling MCP, depois modelo local e API configurada. Sem origem, mantém a recuperação estrutural.
TAMBÉM NA BRANCH
Cross-encoder local e braço estrutural opcionais; tokenizer SmolLM2 embarcado; métricas de respostas; teto de busca de 6.000 tokens / 24.000 bytes / 24.000 caracteres no perfil full; log de reindexação em background limitado a 256 KiB. Cada teto é aplicado independentemente.
02 / GUIA DE MIGRAÇÃO
Duas versões.
Uma atualização consciente.
A versão do programa e o formato do índice são diferentes. Atualize o pacote e reconstrua o índice de cada projeto para liberar a nova estrutura.
PROGRAMA2.1.1 → 3.0.0
Versão declarada em pyproject.toml.
ÍNDICE2.1.0 → 2.3.0
Formato persistido em manifest.json.
LEITURA LEGADA≥ 2.0.0
Continua buscável. Atualizar é outra operação.
Atenção à conversão. Um índice legado anterior a 2.3.0 rejeita atualização incremental e reconstrução parcial. A conversão exige
--full sem --paths, ou atlas_index(full=true) sem paths. Faça isso antes de reativar o watcher e a atualização automática.- 01
Pare o MCP e preserve o índice
Feche a conexão do Atlas no editor. Na raiz do projeto indexado, copie
.code-indexpara um backup com nome ainda não usado. Preserve também a configuração anterior do MCP. - 02
Use o mesmo código no CLI e no MCP
O comando abaixo executa o pacote sem exigir instalação global. Python 3.11–3.13 e
uvsão necessários. Se você usa instalação por ferramenta, atualize-a também comuv tool upgrade codesteer-atlasquando o canal já contiver a versão desejada. - 03
Atualize a conexão e reinicie
Use o configurador abaixo para gerar o MCP com a mesma revisão do comando. Para plugin, atualize pelo canal do seu cliente; um plugin ainda apontando à main antiga não usa o snapshot desta branch.
Gerar minha configuração ↗ - 04
Confira antes de voltar ao trabalho
Peça
atlas_status(): confiraindex_version = 2.3.0, o caminho emindex_resolutione a atualidade do índice. Experimente uma busca conhecida eatlas_context. Com Jev, confirarelevance, faça uma busca e leia o ledger de custo.Depois da conversão,
atlas-index --workspace .e recortes com--pathsvoltam a servir para atualizações incrementais.
Como voltar à instalação anterior?
Pare o MCP. Restaure a revisão e as variáveis anteriores da conexão. Mova o índice novo para outra pasta e recoloque o backup original em .code-index. Reinicie o cliente e confira atlas_status. O backup deve acompanhar a versão do programa; este guia não presume uma conversão reversa do schema.
03 / RELEVÂNCIA COM JEV
A busca encontra.
O Jev avalia.
Um estágio remoto opcional depois da recuperação local. Não exige ativar a camada semântica e não gera embeddings do índice.
01 · LOCALVetor + BM25
→Recuperam candidatos.
02 · LOCALRRF + lexical
→Fundem e ordenam o pool.
03 · OPENROUTERJev · score + confiança
→Refina a relevância.
04 · RESPOSTAtop_k + orçamento
Compacto pode cortar itens.
O que você precisa configurar
Ative ATLAS_RELEVANCE=1, informe a URL System One e a chave do OpenRouter. O modelo padrão é ~typesafe/jev-latest; não herda o modelo da camada semântica.
Deixe ATLAS_RERANK ausente ou diferente de 0. Com 0, toda reordenação é desligada, inclusive Jev e cross-encoder. Reinicie o MCP após mudar o env.
Fronteira de dados. A consulta e trechos dos candidatos saem da máquina para o OpenRouter. Há custo de API. Com Jev e semântica externa desligados, a busca padrão continua local.
RUBRICA V2 · PADRÃO
03Evidência direta
02Contexto de apoio
01Menção de passagem
00Não relacionado
No compacto, score abaixo de 1,5 sai do top_k sem reposição. Correspondências exatas e não avaliados ficam; incertos também podem sair. Se tudo sair, retorna o primeiro local com aviso.
EVIDÊNCIA, COM CONTEXTO
Medido fora da amostra.
38 consultas novas, avaliação de 24/09/2026, top_k=10, rubrica v2 com corte. MRR mede quão cedo aparece o alvo correto; maior é melhor.
0,697MRR com Jev v20,507 no ranking local
−39%tokens de metadadosna mesma avaliação
Resultados deste corpus, não uma garantia para outros projetos. O modelo pode variar. O estudo registrou aproximadamente US$ 0,001 por busca com top_k=10; confira o ledger real, pois preço e consumo podem mudar.
O que acontece em falha, timeout ou baixa confiança?
Timeout, HTTP ou contrato inválido preservam o fallback local no lote afetado. O pool chega ao Jev na ordem lexical; candidatos sem reordenação confiante mantêm essa posição. O cross-encoder configurado atua no fallback, em vez de rodar junto com o Jev. O corte compacto também considera avaliações incertas válidas.
O lote tem teto de 192.000 bytes, até duas chamadas em overflow e timeout compartilhado de 3 segundos. atlas_status.relevance declara configuração sem testar a rede; só uma busca exercita a API.
Como reduzir chamadas ou alterar o corte?
ATLAS_RELEVANCE_GATE=1 dispensa o Jev quando há um único símbolo exato no pool. identifier dispensa qualquer consulta-identificador, inclusive parcial, mas perde a reordenação e o corte Jev nessas consultas. No replay de 24/09, as chamadas caíram de 28 para 13 e o MRR de 0,613 para 0,569; houve mais tokens.
ATLAS_RELEVANCE_CUT=0 volta à seleção conservadora: remove apenas score ≤ 1/8 da escala com confiança ≥ 0,90. ATLAS_RELEVANCE_RUBRIC=v1 usa a rubrica antiga de três níveis; a v2 foi melhor no holdout. Esses controles são opcionais.
Posso reutilizar a chave da camada semântica?
Sim, se ATLAS_SEMANTIC_API_URL for o endpoint HTTPS de chat do OpenRouter (https://openrouter.ai/api/v1/chat/completions). Nesse caso, a URL System One é derivada e ATLAS_SEMANTIC_API_KEY pode ser reutilizada. Em outros casos, configure URL e chave próprias do Jev. O endpoint Jev aceito é https://openrouter.ai/api/v1/systemone.
04 / CONFIGURAÇÃO PRONTA
Seu próximo
mcp.json.
Escolha o perfil e copie. O exemplo usa o formato do Cursor. Em outros clientes, adapte o manifest e informe o caminho absoluto do índice se não houver expansão de ${workspaceFolder}.
A chave no exemplo é um placeholder. Substitua no ambiente local; o site não solicita, guarda ou testa credenciais. Não versione uma chave real.
Revisão do pacote: befec33 ↑05 / NA CONVERSA COM O AGENTE
Encontre. Entenda.
Expanda o necessário.
Omita response_profile nas chamadas normais para respeitar a configuração do operador. full sobrescreve a compactação.
Cheguei ao projeto
atlas_brief()Um briefing basta para orientar a primeira investigação.
Quero localizar a lógica
atlas_search(
query="como o login é validado?",
top_k=5
)Comece pelos metadados. Com Jev e compacto, top_k é um teto.
Já conheço o alvo
atlas_context(
target="src/auth/service.py",
intent="debug"
)Exemplo ilustrativo: use um caminho real do seu projeto. Intents: edit, debug, review e understand.
Falta evidência
atlas_expand(refs=["REF_DO_RESULTADO"])
atlas_graph(
mode="affected",
target="src/auth/service.py"
)Abra uma ou duas refs reais por vez. No outline, escolha os métodos necessários. O grafo mostra impacto pelas relações disponíveis.
OBSERVABILIDADE
ATLAS_OBSERVABILITY=1 registra métricas locais em .code-index/observability/events.jsonl. O tokenizer embarcado mede o texto devolvido; não representa a cobrança do editor. O custo remoto do Jev aparece separadamente no ledger em stderr por busca.
06 / CAMADAS OPCIONAIS
Ative o que
seu projeto precisa.
Jev, compactação, watcher, SCIP e semântica são controles independentes. Atualizar a versão não os liga automaticamente.
| Capacidade | Como ligar | O que conferir |
|---|---|---|
| WatcherAtualização após salvar | ATLAS_WATCH=1Instale o extra | atlas_status.watch: active, disabled, unavailable ou failed. Sem o extra, não observa. |
| SCIPGrafo de chamadas | ATLAS_SCIP=1Instale o indexador da linguagem, como scip-python ou scip-typescript, e reindexe. | atlas_index: scip_status e scip_edges. Sem toolchain: toolchain_missing. Arestas calls declaram origin=scip. |
| SemânticaPropósito por símbolo | ATLAS_SEMANTIC=1Configure uma origem. Ordem: sampling MCP síncrono → ATLAS_SEMANTIC_LOCAL_URL → ATLAS_SEMANTIC_API_URL. Para APIs OpenAI-compatible, informe ATLAS_SEMANTIC_MODEL. | atlas_status.semantic declara origem e egress. API externa envia código à origem. Full/async, CLI e watcher não usam sampling; precisam de endpoint configurado. |
| Cross-encoderReordenação local | ATLAS_RERANK_MODELExemplo: Xenova/ms-marco-MiniLM-L-6-v2. Sem ele, permanece o lexical. | Falha de carga: cross_encoder_unavailable. Com Jev, atua no fallback. ATLAS_RERANK=0 desliga ambos. |
| Braço estruturalRelações no ranking | atlas_search(..., structural=True)Ativado por chamada, com grafo disponível. | Grafo ausente: structural_arm_unavailable. Mantido opt-in por regressões em classes específicas de consulta. |
Por que uma linguagem indexada pode não ter relações?
Suporte de parsing não garante resolução de imports ou chamadas. Confira resolution_coverage: tiers scip, treesitter e none. Não conclua ausência de dependências para linguagens sem resolução. Índices anteriores a 2.2.0 declaram cobertura desconhecida.
07 / FONTES & ESCOPO
Notas rastreáveis
ao código.
Comparação de 35 commits exclusivos da branch. Base remota conferida por fetch em 15/10/2026: origin/main 9301b52 → v3.0 befec33. A main local estava atrasada; a análise usa a referência remota. A árvore local já continha uma reformulação visual, preservada neste trabalho.
Comparação completa ↗Changelog e cortes de versão ↗Regra de conversão do índice ↗Jev, contratos e medições ↗Resolução de configuração Jev ↗Defaults, limites e flags ↗
Todas as funcionalidades apresentadas integram a versão 3.0.0, preparada para lançamento em 15/10/2026. O changelog consolida esta entrega; as referências técnicas e as medições preservam o snapshot de origem. Os exemplos são gerados localmente no navegador e não executam migrações nem chamadas pagas.