Compatibilidad del SDK y la CLI

SDK de GitHub Copilot se comunica con CLI de GitHub Copilot 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

No disponible en el SDK (solo la CLI)

Soluciones alternativas

Exportación de sesión

La --share opción no está disponible a través del SDK. Para solucionar este problema:

• 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.getMessages();
  // Format as markdown yourself
  

• Use la CLI directamente 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 y otras), 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,
});

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,
  });
});

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.compaction.compact();
console.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`);

// 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.compaction.compact();
console.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`);

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();

// 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" });

// 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 de SDK (consulte Soluciones alternativas anteriores).
• Use la CLI directamente: Para las operaciones puntuales, invoque la CLI.
• Solicite la característica: Abra un problema en el repositorio github/copilot-sdk para solicitar compatibilidad con el protocolo.

Compatibilidad de versiones

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.

Puede comprobar las versiones en tiempo de ejecución:

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

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