Visão Geral
O CopilotSpeaker Listener é a API que conecta o agente Jarvis ao Visual Studio e VS Code.
Através dos endpoints expostos, o Jarvis consegue coletar contexto, navegar entre projetos, ler arquivos
e enviar prompts — tudo de forma programática e em tempo real.
Transporte via requestB64 — Todos os endpoints GET recebem parâmetros via query parameter
requestB64: JSON serializado em UTF-8, codificado em Base64 URL-safe (RFC 4648 §5, sem padding).
conversation é obrigatório — Todas as chamadas devem incluir o campo conversation
com pelo menos conversation.text descrevendo a ação. A API tolera ausência mas retorna warnings.
POST /prompt é a exceção — É o único endpoint que usa POST com body JSON.
Todos os demais são GET com requestB64.
Algoritmo de codificação (UTF-8 → Base64Url)
1. Construir objeto JSON com os parâmetros
2. Serializar para string JSON (UTF-8)
3. Converter para byte[] usando Encoding.UTF8.GetBytes(json)
4. Codificar Base64: Convert.ToBase64String(bytes)
5. Substituir: '+' → '-', '/' → '_'
6. Remover padding '=' do final
7. Chamar: GET /endpoint?requestB64=<resultado>
Prompt e Comunicação
Endpoints para enviar comandos ao Copilot Chat, verificar se o listener está ativo
e atualizar o estado visual do Jarvis na interface.
Envia um prompt para o Copilot Chat com controle de thread.
prompt
string
obrigatório
— Texto a ser enviado para o Visual Studio / Copilot.
action
string
— insert (padrão), new ou clear. Controla comportamento de thread.
solution
string?
— Nome da solution alvo (apenas o nome, nunca path completo).
conversation
object
obrigatório
— Contexto de conversa com pelo menos text.
Único endpoint que usa POST com body JSON (UTF-8). Todos os outros são GET.
Verifica se o listener está ativo e respondendo.
conversation
object
obrigatório
— Contexto de conversa via requestB64.
Atualiza título, texto e estado visual do Jarvis em tempo real na UI.
text
string
obrigatório
— Texto principal da UI.
title
string?
— Título curto acima do texto principal.
state
enum
— idle, thinking, speaking, success, warning, error.
Contexto do Projeto
Endpoints para coletar contexto completo do projeto ativo e entender a estrutura da solution
sem precisar abrir cada arquivo manualmente.
Retorna contexto do projeto ativo, arquivo aberto e documentos .md/.agent.
solution
string?
— Nome da solution (usa ativa se omitido).
conversation
object
obrigatório
— Contexto de conversa via requestB64.
Retorna também o esqueleto da solution quando configurado, e a lista de solutions abertas
no VS e VS Code.
Retorna apenas a estrutura da solution — projetos, frameworks, referências — sem código.
solution
string?
— Nome da solution alvo (opcional).
conversation
object
obrigatório
— Contexto de conversa via requestB64.
O ConversationContext é obrigatório em todas as requisições. Deve conter pelo menos
conversation.text com uma frase humana descrevendo a ação. Exemplo:
{"conversation": {"text": "Coletando contexto do projeto"}}
Navegação entre Projetos
Endpoints para listar solutions abertas no Visual Studio e VS Code, selecionar a solution ativa
e trocar o contexto de trabalho sem sair da conversa.
Lista solutions abertas no VS e VS Code com seus arquivos abertos.
conversation
object
obrigatório
— Contexto de conversa via requestB64.
Define a solution ativa para operações subsequentes.
solution
string
obrigatório
— Nome da solution (apenas o nome, ex: InfoMarcas2).
conversation
object
obrigatório
— Contexto de conversa via requestB64.
Remove a seleção de solution ativa, voltando ao estado neutro.
conversation
object
obrigatório
— Contexto de conversa via requestB64.
Privacidade — Sempre use apenas o nome da solution (ex: InfoMarcas2),
nunca o path completo, para proteger a privacidade do usuário.
Arquivos e Leitura
Endpoints para listar, ler, buscar e processar arquivos em lote. Cada um serve um propósito
diferente — desde a listagem de estrutura até a busca inteligente por termos no conteúdo.
Lista arquivos agrupados por projeto, sem conteúdo. Ideal para entender a estrutura.
extensions
string?
— Filtro por extensões (ex: .cs,.xaml).
maxDepth
int
— Profundidade máxima de subdiretórios (default: 6).
conversation
object
obrigatório
— Contexto de conversa via requestB64.
Lê conteúdo de um arquivo específico pelo caminho relativo. Suporta paginação.
relativePath
string
obrigatório
— Caminho relativo do arquivo à raiz da solution.
maxLines
int?
— Limite de linhas. Ajustar: 100 (rápida), 500 (normal), 2000 (completo).
startLine
int
— Linha inicial para leitura, 1-based (default: 1).
Busca arquivos por termos, rankeia por relevância e lê conteúdos automaticamente.
q
string
obrigatório
— Termos de busca separados por espaço. Aspas agrupam frase exata.
extensions
string?
— Extensões separadas por vírgula.
maxFiles
int
— Máximo de arquivos retornados com conteúdo (default: 25).
Este é o endpoint recomendado para buscar código. Ele combina listagem + leitura + ranking,
economizando chamadas em relação ao uso de /solutions/files + /file.
Lê conteúdo de múltiplos arquivos em lote por paths. Prefira /files/content para busca por termos.
paths
string[]
obrigatório
— Lista de caminhos relativos a serem lidos.
maxLinesPerFile
int?
— Máximo de linhas por arquivo (default: ~200).
Diferenças entre os endpoints:
• /solutions/files — Lista estrutura (sem conteúdo)
• /file — Lê um arquivo específico com paginação
• /files/content — Busca por termos + leitura automática (recomendado)
• /files/content/batch — Leitura em lote por paths (legado)
Regras Técnicas Importantes
requestB64
Todos os endpoints GET recebem parâmetros via query parameter requestB64.
O payload é JSON → UTF-8 → Base64 URL-safe. Limite máximo: 16 KB.
Base64Url em UTF-8
A serialização JSON usa UTF-8. O encoding Base64 substitui + por -,
/ por _ e remove padding =.
conversation.text
Campo obrigatório em todas as chamadas. Deve conter uma frase humana descrevendo a ação
no contexto do projeto. A API tolera ausência mas retorna warnings[].
Nome da Solution
Sempre use apenas o nome da solution (ex: InfoMarcas2),
nunca o path completo, para proteger a privacidade do usuário.
Limites Configuráveis
Leitura de arquivos possui limites ajustáveis: maxLines (default: 2000),
maxChars (250k), cacheSeconds (10). O agente pode sobrescrever na requisição.
Erros de Encoding
Base64 inválido → 400 (INVALID_BASE64).
JSON inválido → 400 (INVALID_JSON).
Payload >16KB → 413 (PAYLOAD_TOO_LARGE).
Prioridade de parsing: (1) requestB64 no path segment (backward compat),
(2) requestB64 como query parameter (preferencial),
(3) parâmetros individuais na query string (deprecated).