Verificação de duplicatas de issues e candidatos a regressão para agentes
Verificação de duplicatas de issues e candidatos a regressão para agentes
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.
Com LOOM_TRACKER_ORG definido e uma fonte registrada, o Loom permite que agentes verifiquem se um bug já foi reportado e classifiquem as mudanças que podem
ter introduzido uma regressão, usando registros do tracker e o histórico de PRs indexado.
Para um repositório
com histórico de PRs indexado e sem tracker, use
histórico de código e candidatos a bisect.
Um tracker é o registro que uma equipe mantém de issues, pull requests, incidentes e execuções de CI, armazenado no ClickHouse da própria equipe. O Loom o lê ao vivo com uma credencial somente leitura e nunca o copia. Toda instrução é escrita com base no contrato de registros, então um novo tracker não exige nenhuma mudança de código: a equipe expõe views com os nomes do contrato ou salva um mapeamento a partir de suas próprias tabelas.
As leituras ao vivo mantêm uma única cópia do registro sob o controle de acesso da equipe, e a
implantação não guarda nada que precise ser apagado. Toda leitura tem um orçamento de tempo e um
circuit breaker; quando a fonte não responde, o resultado informa tracker_unavailable.
O Loom mantém apenas estado derivado: embeddings de similaridade (loom.qa_item_embeddings),
vínculos issue→PR recuperados (loom.qa_link_candidates), um resumo diário de CI por teste
(loom.qa_test_daily), o ajuste de calibração da verificação de duplicatas e as fontes registradas
(loom.qa_sources, com credenciais criptografadas).
Portabilidade e tipos de registro
O plano de tracker é neutro em relação ao repositório. Jira, GitHub, GitLab, Linear, um help desk ou um tracker interno podem atender ao mesmo contrato por meio de views do ClickHouse ou de um mapeamento salvo; nenhum nome de repositório ou fornecedor é selecionado no código. Os registros lógicos obrigatórios são issues e pull requests/changes. Os nomes de tabela do contrato são github_issues e github_prs, mas o modo de mapeamento os apresenta no painel como itens e alterações, de modo que as tabelas e colunas da própria fonte não precisam ter esses nomes.
Registros estruturados opcionais habilitam mais operações: incidentes, casos de suporte, threads de chat, snapshots de risco de componentes, releases e saúde de releases, histórico de versões, verificações de CI, instâncias de nuvem e seus relacionamentos. São registros de tabela tipados, não anexos de arquivo. PDFs, arquivos do Office e documentos arbitrários pertencem ao plano Library; vincule suas URLs a partir das linhas do tracker quando uma issue precisar citá-los.
Um repositório pode vincular vários namespaces de tracker em ordem. As consultas por número usam o primeiro tracker, porque #42 é ambíguo entre sistemas. A busca semântica, a verificação de duplicatas, o roteamento de respostas e as varreduras de candidatos de bisect leem todos os trackers vinculados aos quais o solicitante tem acesso, e cada item retornado informa o namespace do seu tracker.
Namespaces de tracker
Um tracker é lido por meio de namespaces de tracker (linhas de diretório com kind = tracker).
Cada um nomeia sua origem e os repos (prefixos Org/repo de source_id) que pode ler; um
repositório que não está listado nunca é lido.
| Tipo | Lê | Política de entrada |
|---|---|---|
| standard | adiciona is_private = 0 a cada instrução; recusa core_incidents, support_cases, slack_threads de imediato |
open (padrão) ou approval |
| restricted | também lê linhas privadas; toda leitura exige um token que nomeie o namespace, além de uma concessão direta ativa | approval |
Os leitores entram com namespace.join (role: "viewer"): um namespace aberto admite na hora,
inclusive contas de serviço; um restrito aguarda o seu administrador. Os layouts e a aplicação das regras
estão em público e privado; o modelo de acesso está em
identidades e namespaces.
As operações
Todas as ops do tracker recebem org (padrão LOOM_TRACKER_ORG) e um namespace obrigatório: um
namespace de tracker ou um namespace de código vinculado a um. Via MCP, cada op é uma ferramenta loom_<op>
(loom_tracker_duplicate_check). O toolset tracker lista as ops de pergunta;
tracker.contract e tracker.source.* podem ser chamadas pelo nome.
| Op | Responde |
|---|---|
tracker.duplicate_check |
Este rascunho já existe? Um veredito calibrado duplicate_of / related / none |
tracker.similar |
Os relatos que já dizem isso: issues e PRs duplicados e relacionados para um text colado, um issue_number ou frames de stack |
tracker.item |
O registro de até dez números de issue ou PR: componente, severidade, veredito de bisect, branches afetadas, testes, CI, backports, o grafo fixes / caused-by |
tracker.links |
Qual PR provavelmente corrigiu esta issue (ou qual issue este PR corrigiu) quando ninguém registrou o vínculo |
tracker.flaky |
Este teste é um flaky conhecido? As issues de teste flaky que o citam, opcionalmente com seu histórico de CI (include_signal) |
tracker.test_signal |
Flaky, regressão ou infraestrutura? O histórico de CI de um único teste |
tracker.release |
Prontidão de release para uma versão: bloqueadores com status e o último snapshot de saúde |
tracker.component |
O snapshot de risco de um componente e suas issues abertas, das mais graves às menos graves |
tracker.answer |
Uma pergunta em prosa, ou as âncoras de um artefato, respondidas por templates nomeados; diz o que pesquisou (explain_only retorna o plano) |
tracker.binding |
O que um namespace pode perguntar ao plano de tracker: seus namespaces de tracker, o primário primeiro, e os templates que o chamador pode executar |
tracker.contract |
O contrato de registro e os templates de view em branco, antes de qualquer conexão |
tracker.source.* |
Registrar, inspecionar, verificar, remapear, rotacionar, listar e remover fontes (contrato de registro) |
O plano de código também lê um tracker vinculado (code.bisect_candidates, code.backport_gap,
code.first_build, code.history, code.context_pack; veja
histórico e PRs), e
loom_search executa a verificação de duplicatas como uma etapa para uma consulta
com formato de defeito sob um escopo de código.
Verificação de duplicatas
tracker.duplicate_check recebe um rascunho como um relator o registraria: title, body,
frames, component, version (X.Y), os números de issue que ele cita em mentions, e
paths e symbols de código.
from loom import Agent
async with Agent(org="acme", namespace="code-widgets", agent="triage-bot") as bot:
res = await bot.tracker.duplicate_check(
namespace="code-widgets",
title="Upload hangs after token refresh",
body="Steps: … Observed: the request never returns.",
component="upload",
paths=["src/upload/client.py"],
)
print(res["verdict"], res["epistemic"], res["answer"])
Ela executa as etapas de tracker.similar uma vez e pontua cada candidato fundido com o ajuste
logístico armazenado do namespace:
- Etapas. BM25F sobre título e corpo com boosts de componente, versão e código de erro;
IDF de frames com decaimento por posição; os itens que o texto nomeia por número; uma etapa vetorial sobre os
embeddings do próprio Loom (
LOOM_TRACKER_SIMILAR_VECTOR_LEG, apenas recall: ela adiciona candidatos, nunca reordena); e uma etapa de correção em andamento: os paths do rascunho → PRs que os alteram → as issues que eles corrigem. - Veredito.
duplicate_ofquando a probabilidade calibrada do primeiro candidato atinge o limiar de duplicata,relatedno limiar de relacionado, senãononesem itens. O ajuste é refeito semanalmente pela passagemtracker_linkssobre as duplicatas rotuladas do próprio registro; o limiar sugerido por cada novo ajuste é servido, limitado porLOOM_TRACKER_DUPCHECK_DUPLICATE_THRESHOLD_MIN/_MAX. - Juiz e rerank. Em uma resposta
related, uma chamada de LLM pode promover um candidato do mesmo defeito aduplicate(nunca rebaixar); uma chamada de rerank ordena as pistas denearest, mas nunca muda o veredito. Ambas exigem um provedor de LLM real e falham de forma aberta. - Vínculos. As linhas de issue trazem seus PRs vinculados, o release em que uma correção é entregue e seus
backports; em
noneourelated,related_prslista PRs que talvez já tratem o rascunho (code.pr_check).
epistemic indica o quanto confiar na resposta:
| Valor | Significa |
|---|---|
calibrated |
há um ajuste armazenado |
uncalibrated |
sem ajuste: no máximo related, confiança nula |
degraded |
uma etapa ou um tracker não respondeu; um none não é liberação |
unavailable |
o tracker não respondeu |
none significa “nenhuma evidência calibrada de duplicata”, não “não reportado”; leia a
lista related de qualquer forma. Quando endereçada a um namespace de código, a verificação lê todos os trackers que o
chamador pode ler, o vinculado primeiro, até LOOM_TRACKER_DUPCHECK_FANOUT_NAMESPACES
(padrão 4), e nomeia o namespace de cada item.
Bisseção
code.bisect_candidates é endereçada ao namespace de código e lê o tracker vinculado a
ele: observações registradas anteriormente nas colunas de triagem de uma issue_number
(triage_reproduces_on, triage_clean_on) fornecem a janela de releases, e os diffs de PR do tracker (github_prs.diff,
affected_file_paths, o recurso bisect do contrato) são varridos em busca dos frames. Sem
frame, a varredura é limitada pelos padrões mais raros da issue
(LOOM_TRACKER_BISECT_SCOPE_PATTERNS) e pelos diretórios do seu componente
(LOOM_TRACKER_BISECT_COMPONENT_DIRS). Sem um tracker, a bisseção lê o próprio
histórico de PRs do repositório. Ela não reproduz a issue nem verifica as observações de triagem; ela
ranqueia PRs para um engenheiro ou agente de teste investigar. O fluxo completo está em
histórico e PRs.
Do rascunho de um bug aos PRs candidatos
Use esta sequência para verificar relatos anteriores e ranquear mudanças integradas sem compilar o repositório. As requisições abaixo ilustram um rascunho; não são resultados registrados.
-
Verifique a configuração. As verificações de duplicatas exigem uma fonte de tracker registrada e um namespace que o chamador possa ler. Para usar o mesmo namespace de código nas duas operações, vincule o tracker e inspecione
tracker.bindingali.kind: "none"pode significar não vinculado ou recusado; isso não estabelece que não existe tracker. Um repositório apenas com histórico de PRs indexado pode ranquear mudanças, mas esse histórico não substitui a verificação de duplicatas do tracker. -
Envie o rascunho para
POST /v1/tracker.duplicate_check, usando o namespace de código vinculado ao tracker. Substitua o escopo de exemplo e as pistas de código pelos do seu repositório:{ "org": "acme", "namespace": "code-widgets", "title": "Upload hangs after token refresh", "body": "The upload request never returns after refreshing its token.", "paths": ["src/upload/client.py"], "symbols": ["UploadClient.send"] }Leia
verdict,epistemic,items,closest,related_prseleg_statusem conjunto. Inspecione os relatos e correções vinculados antes de tratá-los como o mesmo defeito.nonenão autoriza concluir que o bug não foi reportado; uma leitura degradada ou indisponível deixa a questão da duplicata sem resolução. -
Se a mudança que introduziu o problema ainda precisa de investigação, envie as pistas de código do relato para
POST /v1/code.bisect_candidatesnesse mesmo namespace de código:{ "org": "acme", "namespace": "code-widgets", "paths": ["src/upload/client.py"], "symbols": ["UploadClient.send"], "text": "Upload hangs after refreshing its token.", "before": "now", "limit": 5 }Informe
issue_numberapenas para um relato real no tracker vinculado primário. Se releases bons e ruins foram observados, informe essas observações como descrito no exemplo de janela de versões. Aqui,before: "now"define o limite superior no momento da requisição; não é um instante de falha observado. Prefira limites de release observados, um limite superior de tempo observado embefore(eafterquando conhecido), ou um commit sabidamente ruim embad_sha. Para um rascunho não registrado como este, omitir todos os limites de release e de tempo resulta emunknowncomno_failing_version; nenhuma varredura de candidatos é executada. Um registro do tracker que já nomeia um commit ou PR introdutor pode, em vez disso, responder sem varredura. A operação não descobre a última versão boa. -
Guarde a evidência junto com a investigação. Leia
candidates_from,epistemic,causes,tracker_unavailablee qualquerpartial/partial_reasonao lado da lista de candidatos.candidates_from: "code_history"identifica o fallback para o histórico do repositório, não uma leitura bem-sucedida do tracker.matched_paths,matched_symbolsescorede cada candidato explicam seu ranking;epistemic: "lower_bound"significa que uma lista vazia não exclui nada. Inspecione o diff e compare o comportamento relatado antes e depois do candidato em uma reprodução ou teste separado. O ranking em si não prova nem o defeito nem sua causa.
Histórico de testes de CI
tracker.test_signal lê as execuções de CI de um teste na tabela checks e responde
flaky, regression_candidate, infra_candidate, no_signal (silêncio, não saúde) ou
unknown_test (com nomes de teste semelhantes). Ela pondera a taxa de falha e seu limite inferior de
Wilson, as alternâncias entre execuções consecutivas, as alternâncias em reexecuções do mesmo commit, as tempestades de falhas em muitos
testes não relacionados (infraestrutura) e a rotatividade dos arquivos de origem do teste. pr_number adiciona a
sequência de resultados do head desse PR; o código-fonte do teste é varrido em busca de indícios de teste flaky.
O worker tracker_test_daily consolida os checks em loom.qa_test_daily diariamente, de modo que uma leitura
busca no remoto apenas as horas ainda não consolidadas. A tabela de checks vem do checks.from da
entrada da fonte (opções da entrada de fonte),
senão da tabela checks da própria fonte, senão de LOOM_TRACKER_CHECKS_FROM; sem nenhuma delas, a op
não tem o que ler. tracker.flaky responde à pergunta mais barata: se issues de teste flaky
citam o teste (flaky_by_issue ou no_flaky_signal).
Vínculos com PRs de correção
Issues costumam ser fechadas sem uma aresta fixes. A passagem diária tracker_links pega cada issue
aberta nos últimos LOOM_TRACKER_LINKS_ISSUE_DAYS (90) dias, ranqueia os PRs do trunk integrados depois
dela (BM25F sobre título e corpo, palavras-chave de fechamento, frames de stack no diff, componente), e
grava os LOOM_TRACKER_LINKS_PER_ISSUE (20) melhores em loom.qa_link_candidates.
tracker.links os serve nas duas direções. Um consumidor que precisa de uma única correção
(code.backport_gap, bisect) usa o primeiro candidato apenas acima de
LOOM_TRACKER_LINKS_MIN_SCORE (1.0) e quando uma palavra-chave de fechamento nomeia a issue.
Vinculando um tracker a um repositório
Um namespace de código lê seus trackers vinculados em ordem. O primeiro é o primário: seus
números são os números de issues e PRs do repositório, então as consultas por número (tracker.item,
fatos de PR, blame, backports, primeiro build) leem somente ele. As buscas (tracker.duplicate_check,
tracker.similar, tracker.answer, a etapa de registros de loom_search, a varredura de candidatos do bisect)
leem todos os trackers vinculados e informam a origem de cada resultado.
| Quem | Como |
|---|---|
| maintainer | code.repo.set_source com tracker_namespaces (admin do repositório e admin de cada tracker que os vínculos do próprio repositório ainda não contenham), ou a seção Trackers do cartão do repositório. Substitui o mapa do operador para esse repositório dentro de LOOM_CODE_REPOS_REFRESH_SECONDS. Um tracker cujos repos não cobrem o repositório é aceito com not_covering. |
| operator | LOOM_TRACKER_CODE_NAMESPACE_BINDINGS_JSON: chaves glob sobre nomes de namespaces de código, cada uma apontando para um namespace de tracker ou uma lista ordenada. Vincula apenas os repositórios do operador (LOOM_CODE_REPOS_JSON ou LOOM_CODE_REPO); um repositório de autoatendimento (code.repo.add) é vinculado pelo seu maintainer. |
Um tracker padrão vinculado é lido por todos os leitores do repositório, então vincular um é uma
delegação duradoura; um novo vínculo exige o admin do tracker, seja ele restrito ou não. Um leitor
do tracker que não seja seu admin recebe 403; qualquer outra pessoa recebe NOT_A_TRACKER_NAMESPACE.
Depois que um admin do tracker vincula um tracker padrão, os admins do repositório decidem quem o lê,
inclusive por meio de uma mudança posterior na política de entrada com code.repo.set_access. Um vínculo
em um repositório do operador, definido antes ou depois de uma branch ser adicionada, também é lido pelos
leitores de cada branch adicionada a partir dele com code.repo.add_branch, e os admins de cada branch
decidem quem entra nessa branch.
LOOM_TRACKER_CODE_NAMESPACE_BINDINGS_JSON='{"code-widgets*": ["tracker-widgets", "tracker-helpdesk"]}'
Uma branch adicionada com code.repo.add_branch a partir de um repositório do operador o registra
como sua raiz (qa_branch_of) e, sem vínculos próprios, lê os vínculos desse repositório,
de modo que um glob alterado pelo operador, ou um vínculo definido no repositório, chega até ela. O
vínculo de um maintainer em um repositório de autoatendimento é copiado para uma nova branch; um vínculo definido
nesse repositório depois é definido em suas branches por um admin do tracker com
code.repo.set_source. Uma branch de um repositório do operador adicionada de novo com o nome de um
namespace removido que tinha vínculos de um maintainer, antes de a limpeza (purge) desse namespace ser executada,
não lê nenhum tracker até que um admin do tracker o vincule com code.repo.set_source.
Os vínculos nunca são deduzidos a partir de nomes, e um vínculo pertence a uma org: duas orgs podem ter o
mesmo nome de namespace de código, e um vínculo definido em uma nunca se aplica na outra. O gate é executado
novamente para quem faz a chamada no namespace vinculado, então um tracker restrito vinculado a um repositório
público continua fechado para qualquer pessoa que o gate recuse. tracker.binding informa a que um
namespace resolve; não vinculado, recusado e “sem tracker” são a mesma resposta
(kind: "none"), então uma recusa não revela nada.
Adicionando um tracker pelo painel
Qualquer membro da organização que esteja autenticado pode adicionar um tracker a partir da lista Trackers na página Repositories, enquanto LOOM_TRACKER_SELF_SERVICE_ENABLED estiver ativada (padrão) e a organização tiver menos de LOOM_TRACKER_SELF_SERVICE_MAX_SOURCES (10) fontes. O fluxo mostra primeiro o contrato, depois a conexão (ou um mapeamento proposto por tracker.source.inspect) e, em seguida, uma verificação com dry_run: true que retorna um rascunho de CREATE OR REPLACE VIEW para cada tabela com falha. O botão Add permanece desativado até que o formulário verificado seja o mesmo que será enviado. Quem faz o registro se torna o primeiro administrador. Os passos como ops, o SQL do usuário somente leitura e o formulário do operador estão em adicionando uma fonte de tracker.
Configurações que alteram o comportamento
| Configuração | Padrão | Efeito |
|---|---|---|
LOOM_TRACKER_ORG |
"" |
a organização à qual os namespaces do tracker pertencem; vazio = nenhum namespace do tracker é atendido |
LOOM_TRACKER_LIVE_SERVE |
on | chave de desligamento: off = toda leitura do tracker responde tracker_unavailable |
LOOM_TRACKER_LIVE_BUDGET_MS, LOOM_TRACKER_LIVE_TIMEOUT_S |
300, 1.5 | orçamento do lado do chamador por leitura e o max_execution_time remoto |
LOOM_TRACKER_CIRCUIT_FAILURE_THRESHOLD, _COOLDOWN_S |
3, 120 | falhas consecutivas que abrem o circuit breaker de uma fonte e por quanto tempo ele permanece aberto |
LOOM_TRACKER_EMBED_ENABLED |
on | a passagem tracker_embed que preenche o ramo vetorial |
LOOM_TRACKER_LINKS_ENABLED |
on | a passagem diária de recuperação de links, que também reajusta a calibração da verificação de duplicatas |
LOOM_TRACKER_TEST_DAILY_ENABLED |
on | a consolidação diária de CI por teste |
As configurações de limiares, ramos, judge, rerank, escopo de bisect e sinais de teste estão na referência de configuração.
Limites e modos de falha
- Uma fonte lenta responde
tracker_unavailable(ou degrada uma perna, indicada emleg_status) dentro do seu orçamento. Cada fonte tem sua própria conexão, seu próprio breaker e seu próprio orçamento, de modo que a indisponibilidade de uma equipe nunca afeta a de outra. - Uma fonte que falha no contrato não atende até que suas views ou seu mapeamento sejam corrigidos; um veredito de falha é verificado novamente após 60 s (verificando uma fonte).
- Não calibrado até que exista um ajuste. A verificação de duplicatas de um novo tracker responde
uncalibratedaté que o reajuste tenha rodado sobre suas duplicatas rotuladas; um namespace restrito usa o ajuste padrão da organização. - A perna vetorial fica atrasada no máximo uma passada, e uma atualização no momento da consulta gera embeddings dos itens
alterados desde a passada dentro de
LOOM_TRACKER_SIMILAR_CATCH_UP_BUDGET_MS. - Tabelas ausentes respondem
not_provided. Incidentes, releases, verificações de CI e as demais tabelas opcionais são lidos somente quando a fonte os fornece.
Relacionados
- Feed do GitHub: mantenha um registro pertencente à equipe com um job agendado da CLI
- Contrato do registro: tabelas, colunas, aliases, modo de mapeamento, fontes
- Histórico e PRs: as ops do plano de código que leem um tracker
- Adicionando repositórios
- O painel
- Referência de configuração
- Referência de operações