tray-tecnologia Antes de responder
Identifique o termo de busca a partir da pergunta do usuário
Rode:
node skills/tray-dev/scripts/search_docs.mjs "<termo>"Use os resultados como fonte primária. Cite o link âncora retornado.
Se a busca retornar 0 resultados, avise o usuário e use seu conhecimento como fallback explicitamente sinalizado.
Se precisar restringir a um recurso, use
--topic=<slug>(ver lista de tópicos).Se precisar de output programático, use
--json.
Visão geral
tray-dev indexa localmente https://developers.tray.com.br (fetch + cache 24h) e oferece busca lexical (BM25) sobre todos os endpoints, campos, exemplos e códigos de erro da API Tray, em < 100 ms p95 com cache quente. Substitui a documentação estática que envelhece entre releases.
A primeira execução faz fetch da página pública (1,6 MB de HTML), converte para Markdown (660 KB), parseia em 820 seções (H1/H2/H3) e indexa em `/.cache/tray-plugin/dev-docs/`. Execuções subsequentes (24h) usam cache.
CLI
Sintaxe
node skills/tray-dev/scripts/search_docs.mjs "<query>"
node skills/tray-dev/scripts/search_docs.mjs --topic=<slug> "<query>"
node skills/tray-dev/scripts/search_docs.mjs --json "<query>"
node skills/tray-dev/scripts/search_docs.mjs --limit=<n> "<query>"
node skills/tray-dev/scripts/search_docs.mjs --no-cache "<query>"
node skills/tray-dev/scripts/search_docs.mjs --refresh
node skills/tray-dev/scripts/search_docs.mjs --list-topics
node skills/tray-dev/scripts/search_docs.mjs --help
Flags
| Flag | Default | Descrição |
|---|---|---|
--topic=<slug> |
(todos) | Filtra por recurso (ex.: produtos, pedidos) |
--json |
false | Output JSON estruturado |
--limit=<n> |
5 | Máximo de resultados |
--no-cache |
false | Força refetch da SPA |
--refresh |
false | Re-indexa sem fazer query |
--list-topics |
false | Lista tópicos disponíveis |
--help |
false | Ajuda |
Exit codes
0query OK (mesmo se 0 resultados)1erro de execução (rede falha + sem cache; falha de parse)2erro de uso (flag desconhecida, query vazia, topic inexistente)
Tópicos disponíveis
Use --list-topics para a lista atualizada. Mapeamento canônico:
| Slug | Recurso |
|---|---|
autorizacao |
OAuth, tokens |
produtos |
Catálogo de produtos |
pedidos |
Pedidos e ciclo |
clientes |
Clientes (PF/PJ) |
webhooks |
Notificações |
variacoes |
SKUs / variações |
categorias |
Árvore de categorias |
marcas |
Marcas |
cupons |
Cupons de desconto |
multicd |
Multi-CD |
frete |
Cálculo de frete |
pagamentos |
Pagamentos (PIX, boleto, cartão) |
notas-fiscais |
NF-e |
status-pedido |
Status customizados |
kits |
Kits / combos |
caracteristicas |
Atributos de produto |
informacoes-loja |
Dados da loja |
carrinho-compras |
Carrinho |
listagem-carrinho |
Listagem de carrinhos |
listas-preco-b2b |
Preços B2B |
usuarios |
Usuários administrativos |
parceiros |
Parceiros |
palavras-chave |
SEO |
newsletter |
Newsletter |
produtos-vendidos |
Histórico de vendas |
imagens-produtos |
Imagens de produtos |
informacoes-adicionais |
Campos extras |
etiquetas-hub |
Etiquetas HUB |
etiquetas-mercado-livre |
Etiquetas ML |
emissores-etiqueta |
Emissores |
configuracao-frete |
Config de frete |
scripts-externos |
JS na vitrine |
Variáveis de ambiente
| Var | Default | Efeito |
|---|---|---|
TRAY_DOCS_CACHE_DIR |
~/.cache/tray-plugin/dev-docs/ |
Override do cache |
TRAY_DOCS_CACHE_TTL_MS |
86400000 (24h) |
Override do TTL |
TRAY_DOCS_BASE_URL |
https://developers.tray.com.br |
Override da URL fonte |
OPT_OUT_INSTRUMENTATION |
unset | true desativa header de telemetria |
Exemplos
# Conceitual
node skills/tray-dev/scripts/search_docs.mjs "como autenticar via OAuth"
# Endpoint específico
node skills/tray-dev/scripts/search_docs.mjs "POST /products"
# Restrito por recurso
node skills/tray-dev/scripts/search_docs.mjs --topic=pedidos "cancelamento"
# Output JSON para integração
node skills/tray-dev/scripts/search_docs.mjs --json "webhook"
# Forçar atualização da doc
node skills/tray-dev/scripts/search_docs.mjs --refresh
Privacidade
Por padrão, o search_docs.mjs envia o header X-Tray-AI-Telemetry: on para developers.tray.com.br indicando origem (não envia conteúdo da query). Para desativar:
export OPT_OUT_INSTRUMENTATION=true
Limitações
- Sinônimos PT-BR cobrem ~23 grupos no MVP. Expansão via PR em
assets/synonyms-pt-br.json. - Stemmer simples (sufixos comuns). Não é Snowball/RSLP completo.
- Sem busca semântica/embeddings (out of scope; lexical é suficiente para o volume da doc).
- O
bodyretornado nos resultados é truncado em 200 caracteres.
Erros comuns
OFFLINE_NO_CACHE— sem rede e sem cache. Rode com rede uma vez para popular cache inicial.INVALID_TOPIC— slug não está no mapa. Use--list-topics.- Resultados zero para query óbvia — provavelmente sinônimo PT-BR faltando. Abra PR em
assets/synonyms-pt-br.json.