Compatibilidad del SDK y 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
Abortar	`abort()`	Cancelar solicitud en curso
Herramientas
Registro de herramientas personalizadas	`registerTools()`	Compatibilidad completa con el esquema JSON
Control de permisos de herramientas
`onPreToolUse` gancho	Permitir/denegar/preguntar
Modificación del resultado de la herramienta
`onPostToolUse` gancho	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 denegar solicitudes
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
Experimental
Administración de agentes	`session.rpc.agent.*`	Lista, seleccionar, deseleccionar, obtener agente actual
Modo flota	`session.rpc.fleet.start()`	Ejecución paralela de subagentes
Compactación manual	`session.rpc.history.compact()`	Active la compactación bajo demanda
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
Slash comandos
`/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 directa
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 <agent>`	Marca de la CLI

Soluciones alternativas

Exportación de sesión

La --share opción no está disponible a través del SDK. Soluciones alternativas:

Recopilar eventos manualmente : suscríbase a eventos de sesión y cree su propia exportación:

const events: SessionEvent[] = [];
session.on((event) => events.push(event));
// ... after conversation ...
const messages = await session.getEvents();
// Format as markdown yourself

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.

const session = await client.createSession({
  onPermissionRequest: approveAll,
});

Seguimiento del uso de tokens

En lugar de suscribirse a eventos de uso /usage,

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:

// 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`);

Nota:

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:

// 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:

// 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:

Buscar alternativas : muchas características tienen equivalentes del SDK (consulte las soluciones anteriores)
Uso directo de la CLI : para las operaciones puntuales, invoque la CLI.
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:

const status = await client.getStatus();
console.log("Protocol version:", status.protocolVersion);

En este artículo