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