SDK 및 CLI 호환성

GitHub Copilot SDK 는 JSON-RPC 프로토콜을 GitHub Copilot 명령 줄 인터페이스 (CLI) 통해 통신합니다. 기능을 SDK에서 사용할 수 있도록 이 프로토콜을 통해 명시적으로 노출해야 합니다. 많은 대화형 CLI 기능은 터미널별로 제공되며 프로그래밍 방식으로 사용할 수 없습니다.

기능 비교

SDK에서 사용 가능

SDK에서 사용할 수 없음(CLI 전용)

해결 방법

세션 내보내기

이 --share 옵션은 SDK를 통해 사용할 수 없습니다. 이 문제의 해결 방법:

• 수동으로 이벤트 수집: 세션 이벤트에 구독하고 내보내기 기능을 직접 설정합니다.

  TypeScript

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

• CLI를 직접 사용하여 일회성 내보내기를 수행합니다.

권한 제어

SDK는 기본적으로 거부 권한 모델을 사용합니다. 앱에서 처리기를 제공하지 onPermissionRequest 않는 한 모든 권한 요청(파일 쓰기, 셸 명령, URL 페치 등)이 거부됩니다.

--allow-all-paths 또는 --yolo 대신에 사용 권한 처리기를 사용하십시오.

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

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

토큰 사용량 추적

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

컨텍스트 압축

/compact를 사용하는 대신 자동 압축을 구성하거나 수동으로 실행합니다.

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

플랜 관리

프로그래밍 방식으로 세션 계획을 읽고 씁니다.

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

메시지 조정

중단하지 않고 현재 LLM 턴에 메시지를 삽입합니다.

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

프로토콜 제한 사항

SDK는 CLI의 JSON-RPC 프로토콜을 통해서만 노출되는 기능에 액세스할 수 있습니다. 사용할 수 없는 CLI 기능이 필요한 경우:

• 대체 항목 확인: 많은 기능에는 SDK와 동등한 기능이 있습니다(위의 해결 방법 참조).
• CLI를 직접 사용합니다. 일회성 작업의 경우 CLI를 호출합니다.
• 기능을 요청합니다.github/copilot-sdk 리포지토리에서 문제를 열어 프로토콜 지원을 요청합니다.

버전 호환성

SDK는 시작 시 CLI와 프로토콜 버전을 협상합니다. SDK는 프로토콜 버전 2~3을 지원합니다. SDK는 v2 CLI 서버에 연결할 때 tool.call 및 permission.request 메시지를 v3 이벤트 모델에 자동으로 적응시켜 코드 변경이 필요하지 않습니다.

런타임에 버전을 확인할 수 있습니다.

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

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