Copilot SDK 调试

启用调试日志记录

要开始排查故障，请启用详细日志记录，以便了解底层进程的运行情况。

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

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

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 参数指定其他位置。

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

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

对于目前不支持传递额外 CLI 参数的 Python 和 Go，请手动使用 --log-dir 运行 CLI 并通过 cliUrl 选项进行连接。更多信息请参阅 调试指南，位于 github/copilot-sdk 仓库。

常见问题

“CLI 未找到”或 “copilot: command not found”

原因：未安装 GitHub Copilot CLI 或未在 PATH 中。

解决方案

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 进行身份验证。

解决方案

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 仓库。

“未找到会话”

原因：尝试使用已被销毁或不存在的会话。

解决方案

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 服务器进程崩溃或未能启动。

解决方案

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 服务器是否正常工作

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

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 模式（默认）

const client = new CopilotClient({
  useStdio: true,  // This is the default
});

const client = new CopilotClient({
  useStdio: true,  // This is the default
});

TCP 模式

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

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

连接到现有服务器

const client = new CopilotClient({
  cliUrl: "localhost:8080",  // Connect to running server
});

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 Schema

   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
   }
   

工具错误未显现

订阅错误事件

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

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

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 示例，请参阅 调试指南，位于 github/copilot-sdk 仓库。

2. 控制台编码：确保使用 UTF-8，以正确处理 JSON。有关 .NET 示例，请参阅 调试指南，位于 github/copilot-sdk 仓库。

macOS

1. Gatekeeper 问题：如果 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
   

获取帮助

如果仍然卡住，请在提交 issue 前收集以下调试信息

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

搜索已有 issue，或在 github/copilot-sdk 仓库中打开新 issue。