# Compatibilidade do SDK e da CLI Este documento detalha quais recursos da CLI do Copilot estão disponíveis por meio do SDK e quais são exclusivos da CLI. ## Overview O SDK do Copilot se comunica com a CLI por meio do protocolo JSON-RPC. Os recursos devem ser explicitamente expostos por meio desse protocolo para estarem disponíveis no SDK. Muitos recursos interativos da CLI são específicos do terminal e não estão disponíveis programaticamente. ## Comparação de funcionalidades ### ✅ Disponível no SDK | Característica | Método SDK | Notes | | ---------------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- | | **Gerenciamento de Sessão** | | | | | | | | Criar sessão | `createSession()` | Suporte completo à configuração | | Retomar sessão | `resumeSession()` | Com espaços de trabalho de sessão infinitos | | Desconectar sessão | `disconnect()` | Liberar recursos na memória | | Destruir sessão *(preterida)* | `destroy()` | Use `disconnect()` em vez disso | | Excluir sessão | `deleteSession()` | Remover do armazenamento | | Listar sessões | `listSessions()` | Todas as sessões armazenadas | | Obter a última sessão | `getLastSessionId()` | Para retomar rapidamente | | Obter sessão em primeiro plano | `getForegroundSessionId()` | Coordenação de várias sessões | | Configurar sessão em primeiro plano | `setForegroundSessionId()` | Coordenação de várias sessões | | **Messaging** | | | | | | | | Enviar mensagem | `send()` | Com anexos | | Enviar e aguardar | `sendAndWait()` | Bloqueia até a conclusão | | Direção (modo imediato) | `send({ mode: "immediate" })` | Injetar no meio da rotação sem anular | | Fila (modo de enfileiramento) | `send({ mode: "enqueue" })` | Buffer para processamento sequencial (padrão) | | Anexos de arquivo | `send({ attachments: [{ type: "file", path }] })` | Imagens codificadas automaticamente e redimensionadas | | Anexos de diretório | `send({ attachments: [{ type: "directory", path }] })` | Anexar contexto de diretório | | Obter histórico | `getEvents()` | Todos os eventos de sessão | | Anular | `abort()` | Cancelar solicitação de disponibilização de versão piloto | | **Ferramentas** | | | | | | | | Registrar ferramentas personalizadas | `registerTools()` | Suporte completo ao esquema JSON | | Controle de permissão da ferramenta | Gancho `onPreToolUse` | Permitir/negar/perguntar | | Modificação do resultado da ferramenta | Gancho `onPostToolUse` | Transformar resultados | | Ferramentas disponíveis/excluídas | | | | `availableTools`, `excludedTools` configuração | Filtrar ferramentas | | | **Modelos** | | | | | | | | Listar modelos | `listModels()` | Com funcionalidades, cobrança, política | | Definir modelo (na criação) | | | | `model` na configuração da sessão | Por sessão | | | Modelo de switch (durante a sessão) | `session.setModel()` | Também via `session.rpc.model.switchTo()` | | Obter o modelo atual | `session.rpc.model.getCurrent()` | Consultar o modelo ativo | | Esforço de raciocínio | | | | `reasoningEffort` Configuração | Para modelos com suporte | | | **Modo de agente** | | | | | | | | Obter o modo atual | `session.rpc.mode.get()` | Retorna o modo atual | | Configurar modo | `session.rpc.mode.set()` | Alternar entre os modos | | **Gerenciamento de Planos** | | | | | | | | Plano de leitura | `session.rpc.plan.read()` | Obter o conteúdo e o caminho de plan.md | | Plano de atualização | `session.rpc.plan.update()` | Escrever conteúdo do plan.md | | Excluir plano | `session.rpc.plan.delete()` | Remover plan.md | | **Arquivos do Workspace**. | | | | | | | | Listar arquivos do espaço de trabalho | `session.rpc.workspace.listFiles()` | Arquivos na área de trabalho da sessão | | Ler arquivo do espaço de trabalho | `session.rpc.workspace.readFile()` | Ler o conteúdo do arquivo | | Criar arquivo de workspace | `session.rpc.workspace.createFile()` | Criar arquivo no workspace | | **Autenticação** | | | | | | | | Obter o status de autenticação | `getAuthStatus()` | Verificar o estado de logon | | Usar token | | | | Opção `gitHubToken` | Autenticação programática | | | **Conectividade** | | | | | | | | Ping | `client.ping()` | Verificação de integridade com carimbo de data e hora do servidor | | Obter o status do servidor | `client.getStatus()` | Informações sobre a versão do protocolo e o servidor | | **Servidores MCP** | | | | | | | | Servidores locais/stdio | | | | `mcpServers` Configuração | Criar processos | | | HTTP/SSE remoto | | | | `mcpServers` Configuração | Conectar-se a serviços | | | **Hooks** | | | | | | | | Uso de pré-ferramenta | `onPreToolUse` | Permissão, modificar args | | Após o uso da ferramenta (sucesso) | `onPostToolUse` | Modificar resultados | | Após o uso da ferramenta (falha) | `onPostToolUseFailure` | Monitorar chamadas de ferramentas com falha, injetar orientações para nova tentativa | | Solicitação do usuário | `onUserPromptSubmitted` | Modificar prompts | | Início/término da sessão | | | | `onSessionStart`, `onSessionEnd` | Ciclo de vida com origem/motivo | | | Tratamento de erros | `onErrorOccurred` | Manipulação personalizada | | **Eventos** | | | | | | | | Todos os eventos de sessão | | | | `on()`, `once()` | Mais de 40 tipos de evento | | | Streaming | `streaming: true` | Eventos delta | | **Configuração da Sessão** | | | | | | | | Agentes personalizados | | | | `customAgents` Configuração | Definir agentes especializados | | | Mensagem do sistema | | | | `systemMessage` Configuração | Acrescentar ou substituir | | | Provedor personalizado | | | | `provider` Configuração | Suporte ao BYOK | | | Sessões infinitas | | | | `infiniteSessions` Configuração | Compactação automática | | | Manipulador de permissões | `onPermissionRequest` | Aprovar/negar solicitações | | Manipulador de entrada do usuário | `onUserInputRequest` | Manipular ask\_user | | Habilidades | | | | `skillDirectories` Configuração | Habilidades personalizadas | | | Habilidades desabilitadas | | | | `disabledSkills` Configuração | Desabilitar habilidades específicas | | | Diretório de configuração | | | | `configDir` Configuração | Substituir a localização de config padrão | | | Nome do cliente | | | | `clientName` Configuração | Identificar o aplicativo no User-Agent | | | Diretório de trabalho | | | | `workingDirectory` Configuração | Definir o cwd da sessão | | | **Experimental** | | | | | | | | Gerenciamento de agentes | `session.rpc.agent.*` | Listar, selecionar, deselecionar, obter o agente atual | | Modo de frota | `session.rpc.fleet.start()` | Execução paralela de sub-agente; ver [Modo de frota](/pt/copilot/how-tos/copilot-sdk/features/fleet-mode) | | Compactação manual | `session.rpc.history.compact()` | Acionar compactação sob demanda | | Truncamento de histórico | `session.rpc.history.truncate()` | Remover eventos de um ponto em diante | | Bifurcação de sessão | `server.rpc.sessions.fork()` | Criar uma bifurcação de uma sessão a partir de um ponto do histórico | ### ❌ Não disponível no SDK (somente CLI) | Característica | Comando/opção da CLI | Reason | | ------------------------------------------- | --------------------------------------- | --------------------------------------------------------------------- | | **Exportação de sessão** | | | | | | | | Exportar para arquivo | | | | `--share`, `/share` | Não está no protocolo | | | Exportar como gist | | | | `--share-gist`, `/share gist` | Não está no protocolo | | | **Interface do usuário interativa** | | | | | | | | Comandos de barra "/" | | | | `/help`, `/clear`, `/exit`, etc. | Somente TUI | | | Caixa de diálogo seletor de agente | `/agent` | Interface do usuário interativa | | Caixa de diálogo do modo Diff | `/diff` | Interface do usuário interativa | | Caixa de diálogo de feedback | `/feedback` | Interface do usuário interativa | | Seletor de tema | `/theme` | Interface do usuário do terminal | | Seletor de modelo | `/model` | Interface do usuário interativa (use o SDK `setModel()` em vez disso) | | Copiar para a área de transferência | `/copy` | Específico do terminal | | Gerenciamento de contexto | `/context` | Interface do usuário interativa | | **Pesquisa & Histórico** | | | | | | | | Pesquisa profunda | `/research` | Fluxo de trabalho TUI com pesquisa na Web | | Ferramentas de histórico de sessão | `/chronicle` | Reunião, dicas, melhorar, reindexar | | Recursos do terminal | | | | | | | | Saída de cor | `--no-color` | Específico do terminal | | Modo de leitor de tela | `--screen-reader` | Accessibility | | Renderização de diff avançado | `--plain-diff` | Renderização de terminal | | Faixa de inicialização | `--banner` | Elemento visual | | Modo de transmissão | `/streamer-mode` | Modo de exibição TUI | | Buffer de tela alternativo | | | | `--alt-screen`, `--no-alt-screen` | Renderização de terminal | | | Suporte ao mouse | | | | `--mouse`, `--no-mouse` | Entrada do terminal | | | **Atalhos de caminho/permissão** | | | | | | | | Permitir todos os caminhos | `--allow-all-paths` | Usar o manipulador de permissões | | Permitir todas as URLs | `--allow-all-urls` | Usar o manipulador de permissões | | Permitir todas as permissões | | | | `--yolo`, `--allow-all`, `/allow-all` | Usar o manipulador de permissões | | | Permissões granulares de ferramenta | | | | `--allow-tool`, `--deny-tool` | Usar o gancho `onPreToolUse` | | | Controle de acesso à URL | | | | `--allow-url`, `--deny-url` | Usar o manipulador de permissões | | | Redefinir ferramentas permitidas | `/reset-allowed-tools` | Comando TUI | | **Gerenciamento de Diretório** | | | | | | | | Adicionar diretório | | | | `/add-dir`, `--add-dir` | Configurar na sessão | | | Listar diretórios | `/list-dirs` | Comando TUI | | Alterar diretório | `/cwd` | Comando TUI | | **Gerenciamento de Plug-in/MCP** | | | | | | | | Comandos de plugin | `/plugin` | Gerenciamento interativo | | Gerenciamento de servidor MCP | `/mcp` | Interface do usuário interativa | | **Gestão de Contas** | | | | | | | | Fluxo de logon | | | | `/login`, `copilot auth login` | Fluxo do dispositivo OAuth | | | Sair | | | | `/logout`, `copilot auth logout` | CLI direta | | | Informações do usuário | `/user` | Comando TUI | | **Operações de sessão** | | | | | | | | Limpar conversa | `/clear` | Somente TUI | | Visão em planta | `/plan` | Somente TUI (use o SDK `session.rpc.plan.*` em vez disso) | | Gerenciamento de sessão | | | | `/session`, `/resume`, `/rename` | Fluxo de trabalho TUI | | | Modo de gerenciamento de frota (interativo) | `/fleet` | Somente TUI (use o SDK `session.rpc.fleet.start()` em vez disso) | | **Gerenciamento de habilidades** | | | | | | | | Gerenciar habilidades | `/skills` | Interface do usuário interativa | | **Gerenciamento de Tarefas** | | | | | | | | Exibir tarefas em segundo plano | `/tasks` | Comando TUI | | **Uso e Estatísticas** | | | | | | | | Uso de token | `/usage` | Assinar eventos de uso | | **Revisão de código** | | | | | | | | Revisar alterações | `/review` | Comando TUI | | **Delegação** | | | | | | | | Delegar ao PR | `/delegate` | Fluxo de trabalho TUI | | **Instalação do terminal** | | | | | | | | Integração do Shell | `/terminal-setup` | Específico do shell | | **Desenvolvimento** | | | | | | | | Alternar experimental | | | | `/experimental`, `--experimental` | Sinalizador de runtime | | | Controle de instruções personalizadas | `--no-custom-instructions` | Sinalizador da CLI | | Exibir/gerenciar instruções | `/instructions` | Comando TUI | | Reindexar espaço de trabalho | `/reindex` | Comando TUI | | Integração de IDE | `/ide` | Fluxo de trabalho específico do IDE | | **Modo não interativo** | | | | | | | | Modo de prompt | | | | `-p`, `--prompt` | Execução de tiro único | | | Prompt interativo | | | | `-i`, `--interactive` | Execução automática e depois interativa | | | Saída silenciosa | | | | `-s`, `--silent` | Amigável ao script | | | Continuar sessão | `--continue` | Retomar o mais recente | | Seleção do agente | `--agent ` | Sinalizador da CLI | ## Soluções alternativas ### Modo de frota O modo de frota está disponível por meio de `session.rpc.fleet.start()` para aplicativos com SDK que desejam que o runtime acione subagentes em paralelo para atingir um objetivo mais amplo. Use-o quando subtarefas independentes puderem ser executadas simultaneamente e, em seguida, ser resumidas pela sessão principal. Para obter um guia completo, consulte [Modo de frota](/pt/copilot/how-tos/copilot-sdk/features/fleet-mode). ### Exportação de sessão A `--share` opção não está disponível por meio do SDK. Soluções alternativas: 1. **Coletar eventos manualmente** – assine eventos de sessão e crie sua própria exportação: ```typescript const events: SessionEvent[] = []; session.on((event) => events.push(event)); // ... after conversation ... const messages = await session.getEvents(); // Format as markdown yourself ``` 2. **Use a CLI diretamente para exportação** - Execute a CLI com `--share` para exportações pontuais. ### Controle de permissão O SDK usa um modelo **de permissões que nega por padrão**. Todas as solicitações de permissão (gravações de arquivo, comandos de shell, buscas de URL etc.) são negadas, a menos que seu aplicativo forneça um `onPermissionRequest` manipulador. Em vez de `--allow-all-paths` ou `--yolo`, use o manipulador de permissões: ```typescript const session = await client.createSession({ onPermissionRequest: approveAll, }); ``` ### Acompanhamento de uso de token Em vez de `/usage`, assine eventos de uso: ```typescript session.on("assistant.usage", (event) => { console.log("Tokens used:", { input: event.data.inputTokens, output: event.data.outputTokens, }); }); ``` ### Compactação de contexto Em vez de `/compact`, configure a compactação automática ou acione-a manualmente: ```typescript // Automatic compaction via config const session = await client.createSession({ infiniteSessions: { enabled: true, backgroundCompactionThreshold: 0.80, // Start background compaction at 80% context utilization bufferExhaustionThreshold: 0.95, // Block and compact at 95% context utilization }, }); // Manual compaction (experimental) const result = await session.rpc.history.compact(); console.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`); ``` > \[!NOTE] > Os limites são taxas de utilização de contexto (0,0-1,0), não contagens absolutas de token. ### Gerenciamento de Planos Ler e escrever planos de sessão de forma programática: ```typescript // Read the current plan const plan = await session.rpc.plan.read(); if (plan.exists) { console.log(plan.content); } // Update the plan await session.rpc.plan.update({ content: "# My Plan\n- Step 1\n- Step 2" }); // Delete the plan await session.rpc.plan.delete(); ``` ### Direção de mensagem Injetar uma mensagem no turno atual do LLM sem interromper: ```typescript // Steer the agent mid-turn await session.send({ prompt: "Focus on error handling first", mode: "immediate" }); // Default: enqueue for next turn await session.send({ prompt: "Next, add tests" }); ``` ## Limitações de protocolo O SDK só pode acessar recursos expostos por meio do protocolo JSON-RPC da CLI. Se você precisar de um recurso da CLI que não esteja disponível: 1. **Verificar se há alternativas** – muitos recursos têm equivalentes do SDK (confira as soluções alternativas acima) 2. **Usar a CLI diretamente** – para operações pontuais, invoque a CLI 3. **Solicitar o recurso** – Abrir um problema para solicitar suporte ao protocolo ## Compatibilidade entre versões | Intervalo do protocolo do SDK | Versão do protocolo CLI | Compatibility | | ----------------------------- | ----------------------- | ---------------------------------------- | | v2–v3 | v3 | Suporte completo | | v2–v3 | v2 | Suportado por adaptadores automáticos v2 | O SDK negocia versões de protocolo com a CLI na inicialização. O SDK dá suporte às versões de protocolo 2 a 3. Ao se conectar a um servidor CLI v2, o SDK adapta automaticamente as mensagens `tool.call` e `permission.request` ao modelo de evento v3, sem necessidade de alterar o código. Verifique as versões em tempo de execução: ```typescript const status = await client.getStatus(); console.log("Protocol version:", status.protocolVersion); ``` ## Consulte também * [Crie seu primeiro aplicativo com tecnologia do Copilot](/pt/copilot/how-tos/copilot-sdk/getting-started) * [Ganchos de sessão](/pt/copilot/how-tos/copilot-sdk/hooks/hooks-overview) * [Using MCP servers with the GitHub Copilot SDK](/pt/copilot/how-tos/copilot-sdk/features/mcp) * [Guia de depuração](/pt/copilot/how-tos/copilot-sdk/troubleshooting/debugging)