{"meta":{"title":"SDK 및 CLI 호환성","intro":"이 문서에서는 SDK를 통해 사용할 수 있는 Copilot CLI 기능과 CLI 전용 기능을 간략하게 설명합니다.","product":"GitHub Copilot","breadcrumbs":[{"href":"/ko/copilot","title":"GitHub Copilot"},{"href":"/ko/copilot/how-tos","title":"방법"},{"href":"/ko/copilot/how-tos/copilot-sdk","title":"코필로트 SDK"},{"href":"/ko/copilot/how-tos/copilot-sdk/troubleshooting","title":"Troubleshooting"},{"href":"/ko/copilot/how-tos/copilot-sdk/troubleshooting/compatibility","title":"Compatibility"}],"documentType":"article"},"body":"# SDK 및 CLI 호환성\n\n이 문서에서는 SDK를 통해 사용할 수 있는 Copilot CLI 기능과 CLI 전용 기능을 간략하게 설명합니다.\n\n\n\n\n\n## Overview\n\nCopilot SDK는 JSON-RPC 프로토콜을 통해 CLI와 통신합니다. 기능을 SDK에서 사용할 수 있도록 이 프로토콜을 통해 명시적으로 노출해야 합니다. 많은 대화형 CLI 기능은 터미널별로 제공되며 프로그래밍 방식으로 사용할 수 없습니다.\n\n## 기능 비교\n\n### ✅ SDK에서 사용 가능\n\n| 특징 | SDK 메서드 | 비고 |\n| ------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------------------------------ |\n| **세션 관리** | | |\n| | | |\n| 세션 만들기 | `createSession()` | 전체 구성 지원 |\n| 세션 다시 시작 | `resumeSession()` | 무한 세션 작업 영역 사용 |\n| 세션 연결 끊기 | `disconnect()` | 메모리 내 리소스 해제 |\n| 세션 삭제 *(사용되지 않음)* | `destroy()` | 대신 `disconnect()`를 사용하세요. |\n| 세션 삭제 | `deleteSession()` | 스토리지에서 제거 |\n| 세션 목록 표시 | `listSessions()` | 저장된 모든 세션 |\n| 마지막 세션 가져오기 | `getLastSessionId()` | 빠른 다시 시작용 기능 |\n| 포그라운드 세션 가져오기 | `getForegroundSessionId()` | 다중 세션 조정 |\n| 포그라운드 세션 설정 | `setForegroundSessionId()` | 다중 세션 조정 |\n| **Messaging** | | |\n| | | |\n| 메시지 보내기 | `send()` | 첨부 파일 포함 |\n| 보내기 및 대기 | `sendAndWait()` | 작업이 완료될 때까지 차단 |\n| 조향(직접 실행 모드) | `send({ mode: \"immediate\" })` | 중간 턴을 중단 없이 삽입 |\n| 대기열 처리(대기열 등록 모드) | `send({ mode: \"enqueue\" })` | 순차적 처리를 위한 버퍼(기본값) |\n| 첨부 파일 | `send({ attachments: [{ type: \"file\", path }] })` | 이미지 자동 인코딩 및 크기 조정 |\n| 디렉터리 첨부 파일 | `send({ attachments: [{ type: \"directory\", path }] })` | 디렉터리 컨텍스트 연결 |\n| 기록 가져오기 | `getEvents()` | 모든 세션 이벤트 |\n| 중단 | `abort()` | 기내 요청 취소 |\n| **Tools** | | |\n| | | |\n| 사용자 지정 도구 등록 | `registerTools()` | 전체 JSON 스키마 지원 |\n| 도구 권한 제어 | | |\n| `onPreToolUse` 후크 | 허용/거부/요청 | |\n| 도구 결과 수정 | | |\n| `onPostToolUse` 후크 | 결과 변환 | |\n| 사용 가능한/제외된 도구 | | |\n| `availableTools`, `excludedTools` 구성 | 필터 도구 | |\n| **모델들** | | |\n| | | |\n| 모델 나열 | `listModels()` | 기능, 청구, 정책 |\n| 모델 설정(생성 시) | | |\n| `model` 세션 구성에서 | 세션당 | |\n| 모델 전환(세션 중) | `session.setModel()` | 또한 다음을 통해 `session.rpc.model.switchTo()` |\n| 현재 모델 가져오기 | `session.rpc.model.getCurrent()` | 활성 모델 검색 |\n| 추론 노력 | | |\n| `reasoningEffort` 구성 | 지원되는 모델의 경우 | |\n| **에이전트 모드** | | |\n| | | |\n| 현재 모드 가져오기 | `session.rpc.mode.get()` | 현재 모드를 반환합니다. |\n| 모드 설정 | `session.rpc.mode.set()` | 모드 간 전환 |\n| **계획 관리** | | |\n| | | |\n| 계획 읽기 | `session.rpc.plan.read()` | plan.md 콘텐츠 및 경로 가져오기 |\n| 계획 업데이트 | `session.rpc.plan.update()` | plan.md 콘텐츠 작성 |\n| 계획 삭제 | `session.rpc.plan.delete()` | plan.md 제거 |\n| **작업 영역 파일** | | |\n| | | |\n| 작업 영역 파일 나열 | `session.rpc.workspace.listFiles()` | 세션 작업 영역의 파일 |\n| 작업 영역 파일 읽기 | `session.rpc.workspace.readFile()` | 파일 콘텐츠 읽기 |\n| 작업 영역 파일 만들기 | `session.rpc.workspace.createFile()` | 작업 영역에서 파일 만들기 |\n| **Authentication** | | |\n| | | |\n| 인증 상태 가져오기 | `getAuthStatus()` | 로그인 상태 확인 |\n| 토큰 사용 | | |\n| `gitHubToken` 옵션 | 코드 기반 인증 | |\n| **인터넷** | | |\n| | | |\n| 핑 | `client.ping()` | 서버 타임스탬프를 사용하여 상태 검사 |\n| 서버 상태 가져오기 | `client.getStatus()` | 프로토콜 버전 및 서버 정보 |\n| **MCP 서버** | | |\n| | | |\n| 로컬/stdio 서버 | | |\n| `mcpServers` 구성 | 프로세스 생성하기 | |\n| 원격 HTTP/SSE | | |\n| `mcpServers` 구성 | 서비스에 연결 | |\n| **후크** | | |\n| | | |\n| 사전 도구 사용 | `onPreToolUse` | 권한, 인수 수정 |\n| 사후 도구 사용(성공) | `onPostToolUse` | 결과 수정 |\n| 사후 도구 사용(실패) | `onPostToolUseFailure` | 실패한 도구 호출 관찰, 재시도 지침 삽입 |\n| 사용자 프롬프트 | `onUserPromptSubmitted` | 프롬프트 수정 |\n| 세션 시작/종료 | | |\n| `onSessionStart`, `onSessionEnd` | 소스/이유가 있는 수명 주기 | |\n| 오류 처리 | `onErrorOccurred` | 사용자 지정 처리 |\n| **Events** | | |\n| | | |\n| 모든 세션 이벤트 | | |\n| `on()`, `once()` | 40개 이상의 이벤트 유형 | |\n| Streaming | `streaming: true` | 델타 이벤트 |\n| **세션 구성** | | |\n| | | |\n| 사용자 지정 에이전트 | | |\n| `customAgents` 구성 | 특수 에이전트 정의 | |\n| 시스템 메시지 | | |\n| `systemMessage` 구성 | 추가 또는 바꾸기 | |\n| 사용자 지정 공급자 | | |\n| `provider` 구성 | BYOK 지원 | |\n| 무한 세션 | | |\n| `infiniteSessions` 구성 | 자동 압축 | |\n| 권한 처리기 | `onPermissionRequest` | 요청을 승인/거부하고, 선택적으로 자동 승인 원격 분석을 위해 `decisionContext`를 첨부합니다 |\n| 사용자 입력 처리기 | `onUserInputRequest` | ask\\_user 처리 |\n| 기술 | | |\n| `skillDirectories` 구성 | 사용자 지정 기술 | |\n| 비활성화된 기술 | | |\n| `disabledSkills` 구성 | 특정 기술 사용 안 함 | |\n| 구성 디렉터리 | | |\n| `configDir` 구성 | 기본 구성 위치 재정의 | |\n| 클라이언트 이름 | | |\n| `clientName` 구성 | User-Agent에서 앱 식별 | |\n| 작업 디렉터리 | | |\n| `workingDirectory` 구성 | 세션 cwd 설정 | |\n| 추가 디렉터리 | | |\n| `additionalDirectories` 구성 | 작업 디렉터리 외부에 대해서도 세션 접근 권한을 부여하고, 재개 시 다시 제공합니다 | |\n| **실험적** | | |\n| | | |\n| 에이전트 관리 | `session.rpc.agent.*` | 현재 에이전트 나열, 선택, 선택 취소, 가져오기 |\n| 플릿 모드 | `session.rpc.fleet.start()` | 병렬 하위 에이전트 실행; [플릿 모드](/ko/copilot/how-tos/copilot-sdk/features/fleet-mode) 참조 |\n| 수동 압축 | `session.rpc.history.compact()` | 요청 시 압축 실행 |\n| 컨텍스트 지우기 | `session.rpc.history.clearContext()` | 터미널 도구에서 대화 컨텍스트 바꾸기 |\n| 기록 잘림 | `session.rpc.history.truncate()` | 지점 이후의 이벤트 제거 |\n| 세션 분기 | `server.rpc.sessions.fork()` | 기록에서 특정 시점의 세션 분기 |\n\n### ❌ SDK에서 사용할 수 없음(CLI 전용)\n\n| 특징 | CLI 명령/옵션 | Reason |\n| ------------------------------------- | -------------------------- | --------------------------------------------- |\n| **세션 내보내기** | | |\n| | | |\n| 파일로 내보내기 | | |\n| `--share`, `/share` | 프로토콜에 없음 | |\n| gist(온라인 코드 저장소)로 내보내기 | | |\n| `--share-gist`, `/share gist` | 프로토콜에 없음 | |\n| **대화형 UI** | | |\n| | | |\n| 슬래시 명령어 | | |\n| `/help`, `/clear`, `/exit`등 | TUI 전용 | |\n| 에이전트 선택 대화 상자 | `/agent` | 대화형 UI |\n| 차이 모드 대화 상자 | `/diff` | 대화형 UI |\n| 피드백 대화 상자 | `/feedback` | 대화형 UI |\n| 테마 선택기 | `/theme` | 터미널 UI |\n| 모델 선택기 | `/model` | 대화형 UI(대신 SDK `setModel()` 사용) |\n| 클립보드로 복사 | `/copy` | 터미널 관련 |\n| 콘텐츠 관리 | `/context` | 대화형 UI |\n| **연구 기록** | | |\n| | | |\n| 심층 연구 | `/research` | 웹 검색을 사용하여 TUI 워크플로 |\n| 세션 기록 도구 | `/chronicle` | 스탠드업, 팁, 개선, 인덱스 다시 작성 |\n| **터미널 기능** | | |\n| | | |\n| 색 출력 | `--no-color` | 터미널 관련 |\n| 화면 읽기 프로그램 모드 | `--screen-reader` | Accessibility |\n| 리치 다이프 렌더링 | `--plain-diff` | 터미널 렌더링 |\n| 시작 배너 | `--banner` | Visual 요소 |\n| 스트리머 모드 | `/streamer-mode` | TUI 표시 모드 |\n| 대체 화면 버퍼 | | |\n| `--alt-screen`, `--no-alt-screen` | 터미널 렌더링 | |\n| 마우스 지원 | | |\n| `--mouse`, `--no-mouse` | 터미널 입력 | |\n| **경로/권한 바로 가기** | | |\n| | | |\n| 모든 경로 허용 | `--allow-all-paths` | 권한 처리기 사용 |\n| 모든 URL 허용 | `--allow-all-urls` | 권한 처리기 사용 |\n| 모든 권한 허용 | | |\n| `--yolo`, `--allow-all`, `/allow-all` | 권한 처리기 사용 | |\n| 세분화된 도구 권한 | | |\n| `--allow-tool`, `--deny-tool` | | |\n| `onPreToolUse` 후크를 사용하다. | | |\n| URL 액세스 제어 | | |\n| `--allow-url`, `--deny-url` | 권한 처리기 사용 | |\n| 허용된 도구 다시 설정 | `/reset-allowed-tools` | TUI 명령 |\n| **디렉터리 관리** | | |\n| | | |\n| 디렉터리 추가 | | |\n| `/add-dir`, `--add-dir` | 세션에서 구성 | |\n| 디렉터리 목록 나열 | `/list-dirs` | TUI 명령 |\n| 디렉터리 변경 | `/cwd` | TUI 명령 |\n| **플러그 인/MCP 관리** | | |\n| | | |\n| 플러그 인 명령 | `/plugin` | 대화형 관리 |\n| MCP 서버 관리 | `/mcp` | 대화형 UI |\n| **계정 관리** | | |\n| | | |\n| 로그인 흐름 | | |\n| `/login`, `copilot auth login` | OAuth 디바이스 흐름 | |\n| 로그아웃 | | |\n| `/logout`, `copilot auth logout` | 직접 CLI | |\n| 사용자 정보 | `/user` | TUI 명령 |\n| **세션 작업** | | |\n| | | |\n| 명확한 대화 | `/clear` | TUI 전용 |\n| 평면도 보기 | `/plan` | TUI 전용(대신 SDK `session.rpc.plan.*` 사용) |\n| 세션 관리 | | |\n| `/session`, `/resume`, `/rename` | TUI 워크플로 | |\n| 플릿 모드(대화형) | `/fleet` | TUI 전용(대신 SDK `session.rpc.fleet.start()` 사용) |\n| **기술 관리** | | |\n| | | |\n| 스킬 관리 | `/skills` | 대화형 UI |\n| **작업 관리** | | |\n| | | |\n| 백그라운드 작업 보기 | `/tasks` | TUI 명령 |\n| **사용 현황 및 통계** | | |\n| | | |\n| 토큰 사용량 | `/usage` | 사용 이벤트 구독 |\n| **코드 검토** | | |\n| | | |\n| 변경 내용 검토 | `/review` | TUI 명령 |\n| **위임** | | |\n| | | |\n| PR에 위임 | `/delegate` | TUI 워크플로 |\n| **터미널 설정** | | |\n| | | |\n| 셸 통합 | `/terminal-setup` | 셸 전용 |\n| **발달** | | |\n| | | |\n| 실험적 기능 전환 | | |\n| `/experimental`, `--experimental` | 런타임 플래그 | |\n| 사용자 지정 지침 컨트롤 | `--no-custom-instructions` | CLI 플래그 |\n| 진단 세션 | `/diagnose` | TUI 명령 |\n| 지침 보기/관리 | `/instructions` | TUI 명령 |\n| 디버그 로그 수집 | `/collect-debug-logs` | 진단 도구 |\n| 작업 영역 다시 인덱싱 | `/reindex` | TUI 명령 |\n| IDE 통합 | `/ide` | IDE 관련 워크플로 |\n| **비대화형 모드** | | |\n| | | |\n| 프롬프트 모드 | | |\n| `-p`, `--prompt` | 단일 실행 | |\n| 대화형 프롬프트 | | |\n| `-i`, `--interactive` | 자동 실행 후 대화형 | |\n| 무음 출력 | | |\n| `-s`, `--silent` | 스크립트 친화적 | |\n| 세션 계속 | `--continue` | 가장 최근 작업에서 다시 시작 |\n| 에이전트 선택 | `--agent ` | CLI 플래그 |\n\n## 해결 방법\n\n### 플릿 모드\n\n플릿 모드는 더 큰 목표를 달성하기 위해 런타임이 병렬 하위 에이전트를 실행하도록 하려는 SDK 애플리케이션에서 `session.rpc.fleet.start()`를 통해 사용할 수 있습니다. 독립적인 하위 작업을 동시에 실행한 다음 메인 세션에서 요약할 수 있을 때 사용합니다. 전체 가이드는 [플릿 모드](/ko/copilot/how-tos/copilot-sdk/features/fleet-mode)을 참조하세요.\n\n### 세션 내보내기\n\n이 `--share` 옵션은 SDK를 통해 사용할 수 없습니다. 대안:\n\n1. **수동으로 이벤트 수집** - 세션 이벤트를 구독하여 자체 내보내기 기능을 구축합니다.\n\n ```typescript\n const events: SessionEvent[] = [];\n session.on((event) => events.push(event));\n // ... after conversation ...\n const messages = await session.getEvents();\n // Format as markdown yourself\n ```\n\n2. **내보내기용으로 CLI를 직접 사용** - 일회성 내보내기용으로 `--share` CLI를 실행합니다.\n\n### 권한 제어\n\nSDK는 **기본적으로 거부** 권한 모델을 사용합니다. 앱에서 처리기를 제공하지 `onPermissionRequest` 않는 한 모든 권한 요청(파일 쓰기, 셸 명령, URL 페치 등)이 거부됩니다.\n\n`--allow-all-paths` 또는 `--yolo` 대신에 사용 권한 처리기를 사용하십시오.\n\n```typescript\nconst session = await client.createSession({\n onPermissionRequest: approveAll,\n});\n```\n\n### 토큰 사용량 추적\n\n대신 `/usage`를 사용하기보다 사용 이벤트에 가입하세요.\n\n```typescript\nsession.on(\"assistant.usage\", (event) => {\n console.log(\"Tokens used:\", {\n input: event.data.inputTokens,\n output: event.data.outputTokens,\n });\n});\n```\n\n### 컨텍스트 압축\n\n`/compact`를 사용하는 대신 자동 압축을 구성하거나 수동으로 실행합니다.\n\n```typescript\n// Automatic compaction via config\nconst session = await client.createSession({\n infiniteSessions: {\n enabled: true,\n backgroundCompactionThreshold: 0.80, // Start background compaction at 80% context utilization\n bufferExhaustionThreshold: 0.95, // Block and compact at 95% context utilization\n },\n});\n\n// Manual compaction (experimental)\nconst result = await session.rpc.history.compact();\nconsole.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`);\n```\n\n> \\[!NOTE]\n> 임계값은 절대 토큰 수가 아닌 컨텍스트 사용률(0.0-1.0)입니다.\n\n### 플랜 관리\n\n프로그래밍 방식으로 세션 계획을 읽고 씁니다.\n\n```typescript\n// Read the current plan\nconst plan = await session.rpc.plan.read();\nif (plan.exists) {\n console.log(plan.content);\n}\n\n// Update the plan\nawait session.rpc.plan.update({ content: \"# My Plan\\n- Step 1\\n- Step 2\" });\n\n// Delete the plan\nawait session.rpc.plan.delete();\n```\n\n### 메시지 조정\n\n중단하지 않고 현재 LLM 턴에 메시지를 삽입합니다.\n\n```typescript\n// Steer the agent mid-turn\nawait session.send({ prompt: \"Focus on error handling first\", mode: \"immediate\" });\n\n// Default: enqueue for next turn\nawait session.send({ prompt: \"Next, add tests\" });\n```\n\n## 프로토콜 제한 사항\n\nSDK는 CLI의 JSON-RPC 프로토콜을 통해서만 노출되는 기능에 액세스할 수 있습니다. 사용할 수 없는 CLI 기능이 필요한 경우:\n\n1. **대안 확인** - 많은 기능에 SDK 등가물이 있습니다(위의 해결 방법 참조).\n2. **CLI 직접 사용** - 일회성 작업의 경우 CLI를 호출합니다.\n3. **기능 요청** - 프로토콜 지원을 요청하는 문제 열기\n\n## 버전 호환성\n\n| SDK 프로토콜 범위 | CLI 프로토콜 버전 | Compatibility |\n| ----------- | ----------- | --------------- |\n| v2-v3 | v3 | 전체 지원 |\n| v2-v3 | v2 | 자동 v2 어댑터에서 지원됨 |\n\nSDK는 시작 시 CLI와 프로토콜 버전을 협상합니다. SDK는 프로토콜 버전 2\\~3을 지원합니다. SDK는 v2 CLI 서버에 연결할 때 `tool.call` 및 `permission.request` 메시지를 v3 이벤트 모델에 자동으로 적응시켜 코드 변경이 필요하지 않습니다.\n\n런타임 시 버전 확인:\n\n```typescript\nconst status = await client.getStatus();\nconsole.log(\"Protocol version:\", status.protocolVersion);\n```\n\n## 참고하십시오\n\n* [첫 번째 Copilot 기반 앱 빌드](/ko/copilot/how-tos/copilot-sdk/getting-started)\n* [세션 후크](/ko/copilot/how-tos/copilot-sdk/hooks/hooks-overview)\n* [GitHub Copilot SDK에서 MCP 서버 사용](/ko/copilot/how-tos/copilot-sdk/features/mcp)\n* [디버깅 가이드](/ko/copilot/how-tos/copilot-sdk/troubleshooting/debugging)"}