Github Copilot Sdk

何时使用

需要在自己的程序里以代码方式驱动 GitHub Copilot 时使用。SDK 通过 JSON-RPC 封装 Copilot CLI，提供会话管理、自定义工具、生命周期钩子、MCP 服务集成与流式输出，支持 Node.js / Python / Go / .NET。

典型场景：构建 Copilot 智能体应用、给 Copilot 注册业务工具、用钩子做权限管控、接入 MCP 服务、用 BYOK 接自有模型、需要会话持久化或长会话。

不该用的边界：

• 只想做普通聊天补全、或接入非 Copilot 的 LLM（直接用对应厂商 SDK）。
• 没有 Copilot CLI 或未认证、且不打算用 BYOK。
• 任务与「程序化驱动 Copilot」无关。

步骤

1. 装好并认证 Copilot CLI（copilot --version 校验），运行时满足 Node.js 18+ / Python 3.8+ / Go 1.21+ / .NET 8.0+。
2. 安装对应语言 SDK 包。
3. 按「客户端 → 会话 → 消息」三步走：建 client、建 session、发消息。
4. 按需叠加能力：流式、自定义工具、钩子、MCP、BYOK、会话持久化。
5. 用完调用 stop()/destroy() 释放进程与会话。

指令

安装（择一语言）：

认证优先级：① 构造器显式 githubToken → ② 环境变量 COPILOT_GITHUB_TOKEN → GH_TOKEN → GITHUB_TOKEN → ③ copilot auth login 存储的 OAuth → ④ gh auth 凭证。

外接独立 CLI 服务（不自动托管进程）：先 copilot --headless --port 4321，再用 new CopilotClient({ cliUrl: "localhost:4321" })。

示例

核心三步（Node.js）：

import { CopilotClient } from "@github/copilot-sdk";
const client = new CopilotClient();
const session = await client.createSession({ model: "gpt-4.1" });
const response = await session.sendAndWait({ prompt: "What is 2 + 2?" });
console.log(response?.data.content);
await client.stop();

Python 等价（注意需 await client.start()）：

client = CopilotClient()
await client.start()
session = await client.create_session({"model": "gpt-4.1"})
response = await session.send_and_wait({"prompt": "What is 2 + 2?"})
print(response.data.content)
await client.stop()

流式输出：建会话时 streaming: true，订阅增量事件。

const session = await client.createSession({ model: "gpt-4.1", streaming: true });
session.on("assistant.message_delta", (e) => process.stdout.write(e.data.deltaContent));
session.on("session.idle", () => console.log());
await session.sendAndWait({ prompt: "Tell me a joke" });

自定义工具：

import { defineTool } from "@github/copilot-sdk";
const getWeather = defineTool("get_weather", {
  description: "Get the current weather for a city",
  parameters: { type: "object",
    properties: { city: { type: "string", description: "The city name" } },
    required: ["city"] },
  handler: async ({ city }) => ({ city, temperature: "72°F", condition: "sunny" }),
});
const session = await client.createSession({ model: "gpt-4.1", tools: [getWeather] });

钩子做工具权限管控（在 onPreToolUse 返回 deny）：

const session = await client.createSession({
  hooks: {
    onPreToolUse: async (input) => {
      if (["shell", "bash"].includes(input.toolName)) {
        return { permissionDecision: "deny", permissionDecisionReason: "Shell access not permitted" };
      }
      return { permissionDecision: "allow" };
    },
  },
});

钩子触发点：onPreToolUse（工具前，权限/改参）、onPostToolUse（工具后，转换/日志）、onUserPromptSubmitted（用户发消息，改写/过滤）、onSessionStart / onSessionEnd、onErrorOccurred（自定义错误处理/重试）。onPreToolUse 输出字段：permissionDecision（allow|deny|ask）、permissionDecisionReason、modifiedArgs、additionalContext、suppressOutput。

MCP 集成（远程 HTTP 与本地 stdio）：

const session = await client.createSession({
  mcpServers: {
    github: { type: "http", url: "https://api.githubcopilot.com/mcp/" },
    filesystem: { type: "local", command: "npx",
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"], tools: ["*"] },
  },
});

BYOK（自带 Key，免 Copilot 订阅）：

const session = await client.createSession({
  model: "gpt-5.2-codex",
  provider: { type: "openai", baseUrl: "https://your-resource.openai.azure.com/openai/v1/",
    wireApi: "responses", apiKey: process.env.FOUNDRY_API_KEY },
});

会话持久化：建会话传自定义 sessionId，重启后 client.resumeSession(id) 恢复；管理用 client.listSessions() / client.deleteSession(id) / session.destroy()。长会话防超限：infiniteSessions: { enabled: true, backgroundCompactionThreshold: 0.80, bufferExhaustionThreshold: 0.95 }。

注意事项

• 调用顺序差异：Python/Go 需先 start()，Node.js/.NET 在 createSession 时隐式启动。
• BYOK 恢复会话时 必须重新提供 provider 配置，密钥不会持久化。
• wireApi：GPT-5 系列用 "responses"，其余用默认 "completions"。
• BYOK provider type 映射：OpenAI/Azure AI Foundry/Ollama → "openai"（Ollama 本地无需 key），Azure OpenAI 原生 → "azure"（baseUrl 不要带 /openai/v1），Anthropic/Claude → "anthropic"。
• 调试：new CopilotClient({ logLevel: "debug" })。常见报错：CLI not found→装 CLI 或设 cliPath；Not authenticated→copilot auth login 或给 githubToken；Session not found→destroy() 后勿再用；Connection refused→检查 CLI 进程、开 autoRestart。
• 关键 API 速查：Node createSession/sendAndWait/stop；Python create_session/send_and_wait/stop；Go CreateSession/SendAndWait/Stop；.NET CreateSessionAsync/SendAndWaitAsync/DisposeAsync。

互见

• GitHub Copilot SDK: https://github.com/github/copilot-sdk
• Copilot CLI 安装: https://docs.github.com/en/copilot/how-tos/set-up/install-copilot-cli
• MCP 协议规范: https://modelcontextprotocol.io
• 同域可参考：claude-api（Anthropic SDK 集成对照）。

采编自 sickn33/antigravity-awesome-skills（MIT），原技能 copilot-sdk。