SDK- und CLI-Kompatibilität

GitHub Copilot SDK kommuniziert mit GitHub Copilot-CLI über das JSON-RPC-Protokoll. Features müssen explizit über dieses Protokoll verfügbar gemacht werden, damit sie im SDK verfügbar sind. Viele interaktive CLI-Features sind terminalspezifisch und nicht programmgesteuert verfügbar.

Funktionsvergleich

Verfügbar im SDK

Im SDK nicht verfügbar (nur CLI)

Problemumgehungen

Sitzungsexport

Die --share Option ist über das SDK nicht verfügbar. Dieses Problem können Sie folgendermaßen umgehen:

• Manuelles Sammeln von Ereignissen: Abonnieren Sie Sitzungsereignisse, und erstellen Sie Ihren eigenen Export:

  TypeScript

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

• Verwenden Sie die CLI direkt für einmalige Exporte.

Berechtigungsverwaltung

Das SDK verwendet ein Berechtigungsmodell, das standardmäßig verweigert. Alle Berechtigungsanforderungen (Dateischreibvorgänge, Shellbefehle, URL-Abrufe und andere) werden verweigert, es sei denn, Ihre App stellt einen onPermissionRequest Handler bereit.

Verwenden Sie anstelle von --allow-all-paths oder --yolo den Berechtigungshandler:

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

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

Tokenverwendungsnachverfolgung

Statt /usage abonnieren Sie Nutzungsereignisse:

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

Kontextkomprimierung

Anstelle von /compact automatische Komprimierung zu konfigurieren oder manuell auszulösen:

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

Planverwaltung

Programmgesteuertes Lesen und Schreiben von Sitzungsplänen:

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

Nachrichtensteuerung

Fügen Sie eine Nachricht in die aktuelle LLM-Runde ein, ohne abzubrechen.

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

Protokollbeschränkungen

Das SDK kann nur auf Features zugreifen, die über das JSON-RPC-Protokoll der CLI verfügbar gemacht werden. Wenn Sie ein CLI-Feature benötigen, das nicht verfügbar ist:

• Suchen Sie nach Alternativen: Viele Features verfügen über SDK-Entsprechungen (siehe oben beschriebene Problemumgehungen ).
• Verwenden Sie die CLI direkt: Rufen Sie bei einmaligen Vorgängen die CLI auf.
• Fordern Sie das Feature an: Öffnen Sie ein Problem im Github/copilot-sdk-Repository , um die Protokollunterstützung anzufordern.

Versionskompatibilität

Das SDK verhandelt Protokollversionen mit der CLI beim Start. Das SDK unterstützt Protokollversionen 2 bis 3. Beim Herstellen einer Verbindung mit einem v2 CLI-Server passt das SDK automatisch tool.call- und permission.request-Nachrichten an das v3-Ereignismodell an – es sind keine Codeänderungen erforderlich.

Sie können Versionen zur Laufzeit überprüfen:

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

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