# Compatibilidad del SDK y la CLI Este documento describe qué funciones de Copilot CLI están disponibles a través del SDK y cuáles son exclusivas de la CLI. ## Visión general El SDK de Copilot se comunica con la CLI a través del protocolo JSON-RPC. Las características deben exponerse explícitamente a través de este protocolo para que estén disponibles en el SDK. Muchas características interactivas de la CLI son específicas del terminal y no están disponibles mediante programación. ## Comparación de características ### ✅ Disponible en el SDK | Feature | Método SDK | Notas | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | **Gestión de sesiones** | | | | | | | | Crear sesión | `createSession()` | Soporte completo de configuración | | Reanudar sesión | `resumeSession()` | Con áreas de trabajo de sesión infinitas | | Desconectar sesión | `disconnect()` | Liberar recursos en memoria | | Destruir sesión *(en desuso)* | `destroy()` | Use `disconnect()` en su lugar | | Eliminar sesión | `deleteSession()` | Quitar del almacenamiento | | Enumerar las sesiones | `listSessions()` | Todas las sesiones almacenadas | | Obtención de la última sesión | `getLastSessionId()` | Para un currículum rápido | | Obtener sesión en primer plano | `getForegroundSessionId()` | Coordinación de varias sesiones | | Establecer sesión en primer plano | `setForegroundSessionId()` | Coordinación de varias sesiones | | **Messaging** | | | | | | | | Enviar mensaje | `send()` | Con datos adjuntos | | Enviar y esperar | `sendAndWait()` | Bloques hasta completarse | | Dirección (modo inmediato) | `send({ mode: "immediate" })` | Inyectar a mitad de giro sin abortar | | Puesta en cola (modo de puesta en cola) | `send({ mode: "enqueue" })` | Búfer para el procesamiento secuencial (valor predeterminado) | | Archivos adjuntos | `send({ attachments: [{ type: "file", path }] })` | Imágenes codificadas automáticamente y cambiadas de tamaño | | Datos adjuntos de directorio | `send({ attachments: [{ type: "directory", path }] })` | Adjuntar contexto de directorio | | Obtener historial | `getEvents()` | Todos los eventos de sesión | | Abort | `abort()` | Cancelar solicitud en curso | | **Herramientas** | | | | | | | | Registro de herramientas personalizadas | `registerTools()` | Compatibilidad completa con el esquema JSON | | Control de permisos de herramientas | | | | `onPreToolUse` enlace | Permitir/denegar/preguntar | | | Modificación del resultado de la herramienta | | | | `onPostToolUse` enlace | Transformación de los resultados | | | Herramientas disponibles o excluidas | | | | `availableTools`, `excludedTools` configuración | Herramientas de filtro | | | **Modelos** | | | | | | | | Enumeración de modelos | `listModels()` | Con funcionalidades, facturación y políticas | | Establecer modelo (en la creación) | | | | `model` en la configuración de sesión | Por sesión | | | Modelo de conmutador (mediados de sesión) | `session.setModel()` | También a través de `session.rpc.model.switchTo()` | | Obtención del modelo actual | `session.rpc.model.getCurrent()` | Consulta del modelo activo | | Esfuerzo de razonamiento | | | | `reasoningEffort` configuración | Para los modelos admitidos | | | **Modo de agente** | | | | | | | | Obtener el modo actual | `session.rpc.mode.get()` | Devuelve el modo actual. | | Establecer modo | `session.rpc.mode.set()` | Cambiar entre modos | | **Administración de planes** | | | | | | | | Leer plan | `session.rpc.plan.read()` | Obtén el contenido y la ruta de acceso de plan.md | | Actualizar plan | `session.rpc.plan.update()` | Escribir el contenido del archivo plan.md | | Eliminar el plan | `session.rpc.plan.delete()` | Eliminar plan.md | | **Archivos del área de trabajo**. | | | | | | | | Enumerar archivos del área de trabajo | `session.rpc.workspace.listFiles()` | Archivos en el área de trabajo de sesión | | Leer el archivo del área de trabajo | `session.rpc.workspace.readFile()` | Leer el contenido de archivos | | Crear archivo de área de trabajo | `session.rpc.workspace.createFile()` | Creación de un archivo en el área de trabajo | | **Autenticación** | | | | | | | | Obtención del estado de autenticación | `getAuthStatus()` | Comprobación del estado de inicio de sesión | | Uso del token | | | | Opción `gitHubToken` | Autenticación mediante programación | | | **Conectividad** | | | | | | | | Ping | `client.ping()` | Verificación de salud con marca de tiempo del servidor | | Obtención del estado del servidor | `client.getStatus()` | Información del servidor y la versión del protocolo | | **Servidores MCP** | | | | | | | | Servidores locales/stdio | | | | `mcpServers` configuración | Generar procesos | | | HTTP/SSE remoto | | | | `mcpServers` configuración | Conexión a los servicios | | | **Hooks** | | | | | | | | Uso previo a la herramienta | `onPreToolUse` | Permisos para modificar argumentos | | Uso posterior de la herramienta (éxito) | `onPostToolUse` | Modificación de los resultados | | Uso posterior a la herramienta (error) | `onPostToolUseFailure` | Observar las llamadas a herramientas con errores, insertar instrucciones de reintento | | Indicador de usuario | `onUserPromptSubmitted` | Modificación de avisos | | Inicio y finalización de la sesión | | | | `onSessionStart`, `onSessionEnd` | Ciclo de vida con origen o motivo | | | Gestión de errores | `onErrorOccurred` | Control personalizado | | **Eventos** | | | | | | | | Todos los eventos de sesión | | | | `on()`, `once()` | Más de 40 tipos de eventos | | | Streaming | `streaming: true` | Eventos delta | | **Configuración de sesión** | | | | | | | | Agentes personalizados | | | | `customAgents` configuración | Definición de agentes especializados | | | Mensaje del sistema | | | | `systemMessage` configuración | Anexar o reemplazar | | | Proveedor personalizado | | | | `provider` configuración | Compatibilidad con BYOK | | | Sesiones infinitas | | | | `infiniteSessions` configuración | Compactación automática | | | Controlador de permisos | `onPermissionRequest` | Aprobar o rechazar solicitudes; opcionalmente, adjuntar un `decisionContext` para la telemetría de aprobación automática | | Controlador de entrada de usuario | `onUserInputRequest` | Gestionar ask\_user | | Habilidades | | | | `skillDirectories` configuración | Aptitudes personalizadas | | | Aptitudes deshabilitadas | | | | `disabledSkills` configuración | Deshabilitar habilidades específicas | | | Directorio de configuración | | | | `configDir` configuración | Invalidar la ubicación de configuración predeterminada | | | Nombre de cliente | | | | `clientName` configuración | Identificación de la aplicación en User-Agent | | | Directorio de trabajo | | | | `workingDirectory` configuración | Establecer el cwd de la sesión | | | Directorios adicionales | | | | `additionalDirectories` configuración | Conceder acceso a la sesión más allá del directorio de trabajo; volver a proporcionar al reanudar | | | **Experimental** | | | | | | | | Administración de agentes | `session.rpc.agent.*` | Lista, seleccionar, deseleccionar, obtener agente actual | | Modo flota | `session.rpc.fleet.start()` | Ejecución paralela del subagente; consulte [Modo flota](/es/copilot/how-tos/copilot-sdk/features/fleet-mode) | | Compactación manual | `session.rpc.history.compact()` | Active la compactación bajo demanda | | Eliminación de contexto | `session.rpc.history.clearContext()` | Reemplazar el contexto de conversación desde una herramienta de terminal | | Truncamiento del historial | `session.rpc.history.truncate()` | Eliminar eventos a partir de un punto | | Duplicación de sesión | `server.rpc.sessions.fork()` | Bifurcar una sesión en un momento del historial | ### ❌ No disponible en el SDK (solo la CLI) | Feature | Comando o opción de la CLI | Reason | | ----------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------- | | **Exportación de sesión** | | | | | | | | Exportar a archivo | | | | `--share`, `/share` | No en el protocolo | | | Exportar a gist de GitHub | | | | `--share-gist`, `/share gist` | No en el protocolo | | | **Interfaz de usuario interactiva** | | | | | | | | Comandos de barra diagonal | | | | `/help`, `/clear`, `/exit`, etc. | Solo TUI | | | Cuadro de diálogo selector de agente | `/agent` | Interfaz de usuario interactiva | | Cuadro de diálogo de modo diff | `/diff` | Interfaz de usuario interactiva | | Cuadro de diálogo de comentarios | `/feedback` | Interfaz de usuario interactiva | | Selector de temas | `/theme` | Interfaz de usuario del terminal | | Selector de modelos | `/model` | Interfaz de usuario interactiva (use el SDK `setModel()` en su lugar) | | Copiar al Portapapeles | `/copy` | Específico del terminal | | Administración de contexto | `/context` | Interfaz de usuario interactiva | | **Investigación e historia** | | | | | | | | Investigación profunda | `/research` | Flujo de trabajo de TUI con búsqueda web | | Herramientas de historial de sesiones | `/chronicle` | Standup, consejos, mejorar, reindexar | | **Características del terminal** | | | | | | | | Salida de color | `--no-color` | Específico del terminal | | Modo de lector de pantalla | `--screen-reader` | Accessibility | | Representación de diferencias enriquecidas | `--plain-diff` | Representación del terminal | | Banner de inicio | `--banner` | Elemento Visual | | Modo de transmisión | `/streamer-mode` | Modo de presentación de TUI | | Búfer de pantalla alternativo | | | | `--alt-screen`, `--no-alt-screen` | Representación del terminal | | | Compatibilidad con el mouse | | | | `--mouse`, `--no-mouse` | Entrada del terminal | | | **Accesos directos de rutas y permisos** | | | | | | | | Permitir todas las rutas de acceso | `--allow-all-paths` | Uso del controlador de permisos | | Permitir todas las direcciones URL | `--allow-all-urls` | Uso del controlador de permisos | | Permitir todos los permisos | | | | `--yolo`, , `--allow-all`, `/allow-all` | Uso del controlador de permisos | | | Permisos de herramientas granulares | | | | `--allow-tool`, `--deny-tool` | Uso del `onPreToolUse` gancho | | | Control de acceso URL | | | | `--allow-url`, `--deny-url` | Uso del controlador de permisos | | | Restablecimiento de las herramientas permitidas | `/reset-allowed-tools` | Comando TUI | | **Administración de directorios** | | | | | | | | Agregar directorio | | | | `/add-dir`, `--add-dir` | Configurar durante la sesión | | | Enumerar directorios | `/list-dirs` | Comando TUI | | Cambio de directorio | `/cwd` | Comando TUI | | **Plugin/MCP Management** | | | | | | | | Comandos de complementos | `/plugin` | Administración interactiva | | Administración del servidor MCP | `/mcp` | Interfaz de usuario interactiva | | **Administración de cuentas** | | | | | | | | Flujo de inicio de sesión | | | | `/login`, `copilot auth login` | Flujo de dispositivo OAuth | | | Cerrar sesión | | | | `/logout`, `copilot auth logout` | CLI directo | | | Información del usuario | `/user` | Comando TUI | | **Operaciones de sesión** | | | | | | | | Borrar conversación | `/clear` | Solo TUI | | Vista en planta | `/plan` | Solo TUI (use el SDK `session.rpc.plan.*` en su lugar) | | Administración de sesiones | | | | `/session`, , `/resume`, `/rename` | Flujo de trabajo de TUI | | | Modo de flota (interactivo) | `/fleet` | Solo TUI (use el SDK `session.rpc.fleet.start()` en su lugar) | | **Administración de aptitudes** | | | | | | | | Administrar habilidades | `/skills` | Interfaz de usuario interactiva | | **Administración de tareas** | | | | | | | | Ver tareas en segundo plano | `/tasks` | Comando TUI | | **Uso y estadísticas** | | | | | | | | Uso de tokens | `/usage` | Suscribirse a eventos de uso | | **Revisión del código** | | | | | | | | Revisión de los cambios | `/review` | Comando TUI | | **Delegación** | | | | | | | | Delegado a Relaciones Públicas | `/delegate` | Flujo de trabajo de TUI | | **Configuración del terminal** | | | | | | | | Integración de Shell | `/terminal-setup` | Específico del shell | | **Desarrollo** | | | | | | | | Alternar el modo experimental | | | | `/experimental`, `--experimental` | Bandera en tiempo de ejecución | | | Control de instrucciones personalizadas | `--no-custom-instructions` | Marca de la CLI | | Diagnóstico de la sesión | `/diagnose` | Comando TUI | | Ver o administrar instrucciones | `/instructions` | Comando TUI | | Recopilación de registros de depuración | `/collect-debug-logs` | Herramienta de diagnóstico | | Volver a indexar el área de trabajo | `/reindex` | Comando TUI | | Integración del IDE | `/ide` | Flujo de trabajo específico del IDE | | **Modo no interactivo** | | | | | | | | Modo de aviso | | | | `-p`, `--prompt` | Ejecución de un solo intento | | | Aviso interactivo | | | | `-i`, `--interactive` | Ejecución automática y, a continuación, interactiva | | | Salida silenciosa | | | | `-s`, `--silent` | Compatible con scripts | | | Continuar sesión | `--continue` | Continuar desde el último punto más reciente | | Selección del agente | `--agent ` | Marca de la CLI | ## Soluciones alternativas ### Modo flota El modo de flota está disponible a través de `session.rpc.fleet.start()` para aplicaciones del SDK que quieran que el entorno de ejecución despliegue subagentes paralelos para un objetivo más amplio. Úselo cuando las subtareas independientes se pueden ejecutar simultáneamente y, a continuación, se resumen mediante la sesión principal. Para obtener una guía completa, consulte [Modo flota](/es/copilot/how-tos/copilot-sdk/features/fleet-mode). ### Exportación de sesión La `--share` opción no está disponible a través del SDK. Soluciones alternativas: 1. **Recopilar eventos manualmente** : suscríbase a eventos de sesión y cree su propia exportación: ```typescript const events: SessionEvent[] = []; session.on((event) => events.push(event)); // ... after conversation ... const messages = await session.getEvents(); // Format as markdown yourself ``` 2. **Use la CLI directamente para la exportación** : ejecute la CLI con `--share` para las exportaciones puntuales. ### Control de permisos El SDK usa un modelo de permisos **de denegación por defecto** . Se deniegan todas las solicitudes de permiso (escrituras de archivos, comandos de shell, capturas de direcciones URL, etc.), a menos que la aplicación proporcione un `onPermissionRequest` controlador. En lugar de `--allow-all-paths` o `--yolo`, use el manejador de permisos. ```typescript const session = await client.createSession({ onPermissionRequest: approveAll, }); ``` ### Seguimiento del uso de tokens En lugar de suscribirse a eventos de uso `/usage`, ```typescript session.on("assistant.usage", (event) => { console.log("Tokens used:", { input: event.data.inputTokens, output: event.data.outputTokens, }); }); ``` ### Compactación de contexto En lugar de `/compact`, configure la compactación automática o desencadene 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] > Los umbrales son relaciones de uso de contexto (0,0-1,0), no recuentos absolutos de tokens. ### Administración de planes Leer y escribir planes de sesión mediante programación: ```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(); ``` ### Encaminamiento de mensajes Inserte un mensaje en el turno LLM actual sin interrumpir: ```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" }); ``` ## Limitaciones del protocolo El SDK solo puede acceder a las características expuestas a través del protocolo JSON-RPC de la CLI. Si necesita una característica de la CLI que no esté disponible: 1. **Buscar alternativas** : muchas características tienen equivalentes del SDK (consulte las soluciones anteriores) 2. **Uso directo de la CLI** : para las operaciones puntuales, invoque la CLI. 3. **Solicita esta función** - Abre una incidencia para solicitar compatibilidad con un protocolo ## Compatibilidad de versiones | Intervalo de protocolos del SDK | Versión del protocolo de la CLI | Compatibility | | ------------------------------- | ------------------------------- | ----------------------------------------- | | v2-v3 | v3 | Soporte completo | | v2-v3 | v2 | Compatible con adaptadores v2 automáticos | El SDK negocia las versiones de protocolo con la CLI al iniciarse. El SDK admite las versiones de protocolo de 2 a 3. Al conectarse a un servidor de CLI v2, el SDK adapta automáticamente los mensajes entre `tool.call` y `permission.request` al modelo de eventos v3, sin necesidad de realizar cambios en el código. Compruebe las versiones en tiempo de ejecución: ```typescript const status = await client.getStatus(); console.log("Protocol version:", status.protocolVersion); ``` ## Consulte también * [Crea tu primera aplicación con tecnología Copilot](/es/copilot/how-tos/copilot-sdk/getting-started) * [Enlaces de sesión](/es/copilot/how-tos/copilot-sdk/hooks/hooks-overview) * [Uso de servidores MCP con el SDK de GitHub Copilot](/es/copilot/how-tos/copilot-sdk/features/mcp) * [Guía de depuración](/es/copilot/how-tos/copilot-sdk/troubleshooting/debugging)