Operações de código
Operações de código
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.
Esta página relaciona perguntas às ops code.*. Todos os argumentos e saídas estão na
referência de operações gerada, e na descrição MCP de cada op.
Chamando uma op de código
Todas as ops de leitura aceitam org / namespace. Quando uma chamada os omite, o transporte MCP usa
o header X-Loom-Code-Scope: <org>/<namespace> que os plugins de agentes de código enviam para o
checkout atual e, caso contrário, o namespace de código padrão do deployment
(LOOM_CODE_ORG / LOOM_CODE_NAMESPACE). Argumentos explícitos têm prioridade, e a autorização
é executada sobre o namespace informado em ambos os casos: um header que nomeia um namespace que o token não consegue
ler é recusado, nunca ampliado. Sem um padrão definido, uma chamada que não informa nenhum namespace é
recusada com um erro de validação.
Várias ops também aceitam namespaces=[…] (até 8) para consultar vários índices de branch de uma só vez.
Toda resposta que retorna resultados traz um trace_run_id; informe o que você fez com os
resultados por meio de code.outcome para que o ranking aprenda com isso.
A mesma chamada em cada superfície:
# HTTP
curl -fsS -X POST "$LOOM_BASE_URL/v1/code.search" \
-H "Authorization: Bearer $LOOM_API_KEY" -H 'Content-Type: application/json' \
-d '{"org":"acme","namespace":"code-myrepo","query":"where are request quotas enforced?","top_k":5}'
MCP, a ferramenta loom_code_search:
{ "query": "where are request quotas enforced?", "namespace": "code-myrepo", "top_k": 5 }
# Python SDK
from loom import Agent
async with Agent("acme", "support", "review-bot") as agent:
# agent.code.* sends no namespace: the server's default code namespace answers
hits = await agent.code.search("where are request quotas enforced?")
# any code namespace, through the generic call (fields win over the Agent's identity)
hits = await agent.call(
"code.search", namespace="code-myrepo", query="where are request quotas enforced?"
)
for u in hits["results"]:
print(u["path"], u["start_line"], u["symbol"], u["tier"])
await agent.code.outcome(hits["trace_run_id"], "used_in_answer")
Listagem MCP. O toolset coding lista code.search, grep, enclosing, ask,
symbol, outline, callers, context_pack, impact, pr_check e
bisect_candidates. O core lista apenas as oito primeiras com LOOM_MCP_CODE_TOOLS=true
(padrão desativado); o tracker lista impact, pr_check e bisect_candidates. Toda outra
op de código pode ser chamada pelo nome ou por meio de loom_op:
loom_op {"op": "code.index_status", "arguments": {"namespace": "code-myrepo"}}. As seguintes
são servidas apenas por HTTP e pelos SDKs: code.outcome, code.refresh, code.reindex,
code.calibrate, code.context_packs, code.coverage.watch, code.coverage.unwatch,
code.scip_ingest, code.scip_status. O nome da ferramenta MCP de uma op é loom_ mais o nome dela
com os pontos trocados por sublinhados. Toolsets: referência do MCP.
CLI. Não há CLI de cliente para as ops de leitura. loom code … (init, backfill,
reconcile, compact, reembed, backfill-prs, scip-full, scip-delta, warm,
describe, stats, …) é a CLI de administração do servidor
(referência da CLI,
operações do índice de código).
Encontrar
| Op | Use quando |
|---|---|
code.grep |
você tem uma string exata. Literal por padrão, regex=true para RE2; mode = matches, files, presence (entre namespaces) ou message (uma mensagem impressa → a instrução que a imprime) |
code.symbol |
você tem um nome: definições com assinatura e intervalo; uses=true acrescenta cada linha que o menciona, near_paths ordena várias definições pelos arquivos em que você está |
code.search |
você tem uma pergunta em palavras. Recuperação híbrida de símbolo + lexical + vetorial; coloque em pattern= um identificador que você já tenha |
code.ask |
você quer uma resposta sintetizada com citações (em cache por pergunta e invalidada quando um arquivo citado muda) |
code.files |
você quer arquivos por nome, glob ou radical do nome base |
code.enclosing |
você tem localizações path:line (até 200) e quer a função que contém cada uma |
code.outline |
você, de outro modo, leria um arquivo inteiro para ver o que há nele |
code.map |
você quer um mapa de orientação dos módulos do repositório |
code.trace |
você tem um stack trace: cada frame resolvido para sua unidade |
Um chamador com relógio próprio passa deadline_ms para code.grep ou code.search
(limitado a 200–60000; 0 significa nenhum, e, se não definido, vale LOOM_CODE_SEARCH_DEADLINE_MS):
a requisição para de iniciar novo trabalho quando o orçamento acaba e devolve o que tem,
partial: true com um partial_reason que nomeia o que não terminou (uma varredura do grep interrompida
pelo break-on-timeout do ClickHouse, uma perna da busca, rerank, HyDE), em vez de expirar por timeout.
Em mode: "message", um padrão que não corresponde a nenhum template de instrução (uma linha de código em vez
de uma mensagem renderizada) passa por grep mais uma vez como literal e a resposta traz
fallback: "literal".
Exemplos.
# Which release branches contain this string? One call, one row per namespace.
curl -fsS -X POST "$LOOM_BASE_URL/v1/code.grep" \
-H "Authorization: Bearer $LOOM_API_KEY" -H 'Content-Type: application/json' \
-d '{"org":"acme","pattern":"retry budget exhausted","mode":"presence","namespaces":["code-myrepo","code-myrepo-2-4"]}'
d = await agent.code.symbol("QuotaLimiter::check", uses_brief=True, include_body=True)
located = await agent.code.enclosing(["src/quota/limiter.py:88", "src/api/routes.py:140"])
Campos de code.search que vale conhecer: path_prefix, path_globs / exclude_globs
(rg -g), langs (rg -t), pattern (restringe as duas pernas a chunks que o contêm),
bodies: "none" (apenas intervalos e assinaturas, a resposta mais barata), token_budget,
expand (um salto de LLM para ligar a redação aos identificadores) e cursor para a próxima página.
Estrutura e mudança
| Op | Use quando |
|---|---|
code.callers |
quem chama isto, depth saltos; uma sobrescrita também informa os chamadores da declaração base |
code.callees |
o que isto chama, depth saltos |
code.impact |
raio de impacto de um símbolo, ou de files / um diff: chamadores, testes que alcançam a mudança, parceiros de co-change |
code.test_gate |
quais testes uma mudança exige, e quais funções alteradas nenhum teste alcança |
code.tests_for |
quais testes cobrem algo |
code.test_home |
onde um novo teste deve ficar |
code.coverage_claim |
“isto já está testado?” |
code.verify |
verifica uma afirmação de forma fechada (“A chama B”, “X sobrescreve Y”) contra o índice |
code.verify_citations |
resolve toda citação path:line / de símbolo em um rascunho antes de enviá-lo |
code.path_guards |
as condições que estão no caminho de chamada entre dois símbolos |
code.examples |
pontos de chamada reais de um símbolo |
code.setting_facts |
o que a árvore diz sobre uma configuração do ClickHouse (declaração, histórico de mudanças, randomização no CI); só faz sentido para uma árvore de código do ClickHouse |
code.callers / code.callees aceitam min_confidence para descartar arestas da camada do parser abaixo de
um grau (as arestas do compilador são sempre 1.0) e include_ambiguous para adicionar os pontos de chamada que o
resolvedor recusou, em um bloco separado candidate_sites. Leia epistemic e causes
na resposta (overview.md).
Exemplo: impacto de um diff.
import subprocess
diff = subprocess.run(["git", "diff", "origin/main"], capture_output=True, text=True).stdout
r = await agent.code.impact(diff=diff, exclude_authors=["me"])
print(r["epistemic"], r.get("causes"))
for row in r.get("co_change_missing", []):
print("usually changes with this diff:", row)
A forma com diff retorna os símbolos que os hunks sobrepõem, os testes que os alcançam e
co_change_missing; files sozinho trata toda função desses arquivos como alterada.
As duas formas retornam owners: autores de PR ponderados por recência sobre os caminhos
de origem, com exclude_authors (normalmente o próprio autor da mudança) removidos. O índice contém
código já integrado, então o diff é lido contra o head do branch; suas funções não commitadas só são resolvidas
quando já existem lá.
Histórico, PRs e releases
Estas operações leem o plano de PRs que o worker code_pr_history preenche a partir do GitHub
(LOOM_CODE_PR_HISTORY_ENABLED). O histórico de um namespace de branch de release contém os PRs
mesclados nessa branch. Como o plano é preenchido, e bisect e backports em detalhe, estão
em history-and-prs.md.
| Op | Use quando |
|---|---|
code.context_pack |
briefing de um PR (pr_number), de uma mudança que você está prestes a fazer (task) ou do repositório; sections mantém apenas os blocos em que você vai agir |
code.history |
PRs mesclados que tocaram um símbolo ou um caminho |
code.symbol_history |
PRs mesclados que alteraram um símbolo, entre duas releases |
code.blame_range |
PRs mesclados por trás de um intervalo de linhas |
code.review_brief |
o que os revisores verificaram em um PR mesclado |
code.conventions |
as verificações de revisão recorrentes do repositório, a partir de um PR |
code.pr_check |
antes de abrir um PR: já existe um PR como este (mesclado, aberto ou fechado)? |
code.bisect_candidates |
quais PRs mesclados podem ter introduzido um bug, a partir de frames, caminhos, símbolos e uma janela good/bad |
code.backport_gap |
quais branches de release ainda carregam o bug que uma correção removeu |
code.backport_gaps |
o relatório do conjunto todo de correções marcadas para backport que alguma branch não tem |
code.first_build |
qual build de CI carregou um commit primeiro |
Exemplo: verificação de duplicidade antes de um PR.
curl -fsS -X POST "$LOOM_BASE_URL/v1/code.pr_check" \
-H "Authorization: Bearer $LOOM_API_KEY" -H 'Content-Type: application/json' \
-d '{"org":"acme","namespace":"code-myrepo","title":"Retry quota refresh on 503","paths":["src/quota/limiter.py"],"symbols":["QuotaLimiter::refresh"]}'
verdict é duplicate_of (um PR aberto está fazendo isso, ou um mesclado já fez), related
ou none; os itens trazem estado, pontuação e linhas de evidência. A verificação é heurística e não faz
nenhuma chamada ao GitHub; um título sozinho nunca é tratado como duplicata.
Status e administração
| Op | Papel | Retorna |
|---|---|---|
code.repos |
viewer | entradas legíveis com atualidade, acesso e etapa de bootstrap; repo / repos restringem a um checkout (um fork do GitHub resolve para o índice do repositório pai) |
code.index_status |
viewer | marcas d’água, atrasos, camadas, commit_coverage (freshness.md) |
code.coverage |
viewer | arquivos, chunks, símbolos por camada, arestas por linguagem, e gaps — o que o índice não conhece |
code.index_errors |
viewer | arquivos em que o indexador falhou |
code.recent_commits |
viewer | commits ingeridos recentemente |
code.context_packs |
viewer | packs de PR armazenados |
code.outcome |
viewer | registra o que você fez com um resultado (opened_file, used_in_answer, fell_back_grep, ignored) |
code.coverage.watch |
viewer | um evento de tarefa code.coverage.ready na sua inbox quando um commit passa a ser coberto; exige writer no namespace dono da inbox |
code.coverage.unwatch |
viewer | remove uma observação pendente |
code.scip_status |
viewer | o estado de um delta da camada do compilador enviado |
code.refresh |
writer | dispara uma passagem de ingestão agora (freshness.md) |
code.scip_ingest |
writer | envia um delta da camada do compilador de um produtor externo (aplicado por code_scip_apply) |
code.reindex |
admin | move a marca d’água de ingestão para um commit |
code.calibrate |
admin | reajusta o piso de ruído e o limiar de abstenção da busca |
Adicionar, ramificar, restringir e remover repositórios (code.repo.add,
code.repo.remote_branches, code.repo.add_branch, code.repo.set_access,
code.repo.set_source, code.repo.remove) estão em
repositories.md.
Relacionados
- overview.md — camadas, suporte a linguagens, como ler uma resposta
- freshness.md —
as_of, cobertura de commits, atualização por CI, coverage watches - history-and-prs.md — o plano de PRs, bisect, backports
- Referência do SDK Python, Referência do MCP
- Referência de operações — argumentos gerados