코필로트 SDK 디버깅

에서 디버그 로깅을 사용하도록 설정하고 일반적인 연결, 인증 및 도구 실행 문제를 해결합니다 코필로트 SDK.

누가 이 기능을 사용할 수 있나요?

GitHub Copilot SDK 는 모든 Copilot 계획에서 사용할 수 있습니다.

이 기사에서

참고

          코필로트 SDK가 현재 공개 미리 보기에 있습니다. 기능 및 가용성은 변경될 수 있습니다.

디버그 로깅 활성화

문제 해결을 시작하려면 자세한 정보 로깅을 사용하도록 설정하여 기본 프로세스에 대한 가시성을 확보합니다.

TypeScript
import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient({
  logLevel: "debug",  // Options: "none", "error", "warning", "info", "debug", "all"
});

Python, Go 및 .NET의 예제는 리포지토리의 디버깅 가이드를github/copilot-sdk 참조하세요. Java의 경우 리포지토리를github/copilot-sdk-java 참조하세요.

로그 디렉터리

CLI는 기본적으로 ABC 디렉터리에 로그를 씁니다. 인수를 사용하여 다른 위치를 지정할 수 있습니다.--log-dir

TypeScript
const client = new CopilotClient({
  cliArgs: ["--log-dir", "/path/to/logs"],
});

현재 추가 CLI 인수 전달을 지원하지 않는 Python 및 Go의 경우 CLI를 수동으로 --log-dir 실행하고 옵션을 통해 cliUrl 연결합니다. 자세한 내용은 리포지토리의 디버깅 가이드 를 github/copilot-sdk 참조하세요.

일반적인 문제

"CLI를 찾을 수 없음" 또는 "부조종사: 명령을 찾을 수 없음"

          **원인:**GitHub Copilot 명령 줄 인터페이스 (CLI) 설치되지 않았거나 PATH에 포함되어 있지 않습니다.

          **Solution:**

  1. CLI를 설치합니다. 자세한 내용은 GitHub Copilot CLI 설치을(를) 참조하세요.

  2. 설치 확인:

    Bash
    copilot --version

  3. 또는 전체 경로를 지정합니다.

    TypeScript
    const client = new CopilotClient({
  cliPath: "/usr/local/bin/copilot",
});

    Python, Go 및 .NET의 예제는 리포지토리의 디버깅 가이드를github/copilot-sdk 참조하세요. Java의 경우 리포지토리를github/copilot-sdk-java 참조하세요.

"인증되지 않음"

          **원인:** CLI가 GitHub와 인증되지 않았습니다.

          **Solution:**

  1. CLI 인증:

    Bash
    copilot auth login

  2. 또는 프로그래밍 방식으로 토큰을 제공합니다.

    TypeScript
    const client = new CopilotClient({
  githubToken: process.env.GITHUB_TOKEN,
});

    Python, Go 및 .NET의 예제는 리포지토리의 디버깅 가이드를github/copilot-sdk 참조하세요. Java의 경우 리포지토리를github/copilot-sdk-java 참조하세요.

"세션을 찾을 수 없음"

          **원인:** 제거되었거나 존재하지 않는 세션을 사용하려고 시도합니다.

          **Solution:**

  1. 다음 후에 disconnect()메서드를 호출하지 않는지 확인합니다.

    TypeScript
    await session.disconnect();
// Don't use session after this!

  2. 세션을 다시 열려면 세션 ID가 있는지 확인합니다.

    TypeScript
    const sessions = await client.listSessions();
console.log("Available sessions:", sessions);

"연결이 거부됨" 또는 "ECONNREFUSED"

          **원인:** CLI 서버 프로세스가 충돌하거나 시작하지 못했습니다.

          **Solution:**

  1. CLI가 올바르게 독립 실행형으로 실행되는지 확인합니다.

    Bash
    copilot --server --stdio

  2. TCP 모드를 사용하는 경우 포트 충돌을 확인합니다.

    TypeScript
    const client = new CopilotClient({
  useStdio: false,
  port: 0,  // Use random available port
});

MCP 서버 디버깅

MCP(모델 컨텍스트 프로토콜) 서버는 디버그하기 어려울 수 있습니다. 포괄적인 MCP 디버깅 지침은 Copilot SDK에서 MCP 서버 디버깅을 참조하세요.

빠른 MCP 검사 목록

  • MCP 서버 실행 파일이 존재하며 독립적으로 실행됩니다.
  • 명령 경로가 올바르다(절대 경로 사용)
  • 도구를 사용할 수 있습니다. tools: ["*"]
  • 서버가 요청에 올바르게 응답합니다 initialize .
  • 작업 디렉터리(cwd)가 필요한 경우 설정됨

MCP 서버 테스트

SDK와 통합하기 전에 MCP 서버가 작동하는지 확인합니다.

Bash
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | /path/to/your/mcp-server

자세한 문제 해결은 Copilot SDK에서 MCP 서버 디버깅을 참조하세요.

연결 문제

Stdio 및 TCP 모드

SDK는 두 가지 전송 모드를 지원합니다.

모드설명사용 사례
          **Stdio** (기본값) | CLI는 하위 프로세스로 실행되며 파이프를 통해 통신합니다. | 로컬 개발, 단일 프로세스 |

| TCP | CLI는 별도로 실행되며 TCP 소켓을 통해 통신합니다. | 여러 클라이언트, 원격 CLI |

          **Stdio 모드(기본값):**
TypeScript
const client = new CopilotClient({
  useStdio: true,  // This is the default
});

          **TCP 모드:**
TypeScript
const client = new CopilotClient({
  useStdio: false,
  port: 8080,  // Or 0 for random port
});

          **기존 서버에 연결:**
TypeScript
const client = new CopilotClient({
  cliUrl: "localhost:8080",  // Connect to running server
});

연결 오류 진단

  1. 클라이언트 상태 확인:

    TypeScript
    console.log("Connection state:", client.getState());
// Should be "connected" after start()

  2. 상태 변경 내용 수신 대기:

    TypeScript
    client.on("stateChange", (state) => {
  console.log("State changed to:", state);
});

  3. CLI 프로세스가 실행 중인지 확인합니다.

    Bash
    # Check for copilot processes
ps aux | grep copilot

도구 실행 문제

사용자 지정 도구가 호출되지 않음

  1. 도구 등록 확인:

    TypeScript
    const session = await client.createSession({
  tools: [myTool],
});

// Check registered tools
console.log("Registered tools:", session.getTools?.());

  2. 도구 스키마가 유효한 JSON 스키마인지 확인합니다.

    TypeScript
    const myTool = {
  name: "get_weather",
  description: "Get weather for a location",
  parameters: {
    type: "object",
    properties: {
      location: { type: "string", description: "City name" },
    },
    required: ["location"],
  },
  handler: async (args) => {
    return { temperature: 72 };
  },
};

  3. 처리기가 유효한 결과를 반환하는지 확인합니다.

    TypeScript
    handler: async (args) => {
  // Must return something JSON-serializable
  return { success: true, data: "result" };

  // Don't return undefined or non-serializable objects
}

도구 오류가 표면에 드러나지 않음

오류 이벤트 구독:

TypeScript
session.on("tool.execution_error", (event) => {
  console.error("Tool error:", event.data);
});

session.on("error", (event) => {
  console.error("Session error:", event.data);
});

플랫폼별 문제

윈도우즈

  1.        **경로 구분 기호:** 원시 문자열 또는 슬래시를 사용합니다. 의 경우 NET 관련 예제는 리포지토리의 [디버깅 가이드](https://github.com/github/copilot-sdk/blob/main/docs/troubleshooting/debugging.md) 를 `github/copilot-sdk` 참조하세요.

  2.        **콘솔 인코딩:** 적절한 JSON 처리를 위해 UTF-8을 확인합니다. 의 경우 NET 관련 예제는 리포지토리의 [디버깅 가이드](https://github.com/github/copilot-sdk/blob/main/docs/troubleshooting/debugging.md) 를 `github/copilot-sdk` 참조하세요.

macOS

  1.        **게이트키퍼 문제:** CLI가 차단된 경우:
    Bash
    xattr -d com.apple.quarantine /path/to/copilot

  2.        **GUI 앱의 PATH 문제:** GUI 애플리케이션은 셸 PATH를 상속할 수 없습니다.
    TypeScript
    const client = new CopilotClient({
  cliPath: "/opt/homebrew/bin/copilot",  // Full path
});

리눅스

  1.        **권한 문제:**
    Bash
    chmod +x /path/to/copilot

  2.        **누락된 라이브러리:** 필요한 공유 라이브러리를 확인합니다.
    Bash
    ldd /path/to/copilot

도움 받기

여전히 문제가 발생하면 문제를 열기 전에 다음 디버그 정보를 수집합니다.

  • SDK 버전
  • CLI 버전(copilot --version)
  • 운영 체제
  • 디버그 로그
  • 최소 복제 코드

기존 문제를 검색하거나 github/copilot-sdk 리포지토리에서 새 문제를 엽니다.