调试 Copilot SDK

启用调试日志记录并解决常见的 Copilot SDK连接、身份验证和工具执行问题。

谁可以使用此功能？

GitHub Copilot SDK 适用于所有 Copilot 计划。

在本文中

注意

          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”或“copilot： 命令未找到”

          **原因：**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);
});

特定于平台的问题

Windows操作系统

  1.        **路径分隔符：** 使用原始字符串或正斜杠。 对于 .NET 特定的示例，请参阅[存储库中的调试指南](https://github.com/github/copilot-sdk/blob/main/docs/troubleshooting/debugging.md)。

  2.        **控制台编码：** 确保使用 UTF-8 正确处理 JSON。 对于 .NET 特定的示例，请参阅[存储库中的调试指南](https://github.com/github/copilot-sdk/blob/main/docs/troubleshooting/debugging.md)。

macOS

  1.        **守护程序问题：** 如果阻止 CLI：
    Bash
    xattr -d com.apple.quarantine /path/to/copilot

  2.        **GUI 应用中的 PATH 问题：** GUI 应用程序可能无法继承 shell PATH：
    TypeScript
    const client = new CopilotClient({
  cliPath: "/opt/homebrew/bin/copilot",  // Full path
});

Linux

  1.        **权限问题：**
    Bash
    chmod +x /path/to/copilot

  2.        **缺少库：** 检查所需的共享库：
    Bash
    ldd /path/to/copilot

获取帮助

如果仍然遇到问题，请先收集以下调试信息，然后再打开问题：

  • SDK 版本
  • CLI 版本 （copilot --version）
  • 操作系统
  • 调试日志
  • 最小复制代码

在 github/copilot-sdk 存储库中搜索现有问题或打开新问题。