@github/copilot-engine-sdk

中文文档
0.3.1发布于 2026/09/02MITTypeScriptES Module构建来源已验证近 30 天下载 1万

SDK for building engines on the GitHub Copilot agent platform

原始使用文档
文档目录17 节
  1. Overview
  2. Installation
  3. Local Development
  4. Quick Start
  5. API Reference
  6. PlatformClient
  7. Git Utilities
  8. MCP Server
  9. MCP Proxy Discovery
  10. Event Factories
  11. CLI — Local Testing
  12. Environment Variables
  13. Documentation
  14. Contributing
  15. Support
  16. Security
  17. License

@github/copilot-engine-sdk

NOTE: This is a library that is used internally for certain integrations. It is not a supported integration path, preview, or released product.

SDK for building engines on the GitHub Copilot agent platform.

Overview

The Copilot Engine SDK provides everything you need to build an engine that runs on the GitHub Copilot agent platform:

  • Platform Client — send structured events (assistant messages, tool executions, progress updates) to the platform API
  • Git Utilities — clone repositories, commit and push changes with secure credential handling
  • MCP Server — a Model Context Protocol server exposing report_progress and reply_to_comment tools
  • MCP Proxy Discovery — discover and connect to user-configured MCP servers
  • Event Factories — create typed platform events for custom event pipelines
  • CLI — local testing harness that simulates the platform for development
  • Integration Guide — step-by-step guide to building an engine

Installation

Until this package is published to a package registry, install it directly from GitHub:

{
  "dependencies": {
    "@github/copilot-engine-sdk": "github:github/copilot-engine-sdk#main"
  }
}

Then run npm install.

Local Development

For local development with a cloned copy of the SDK:

# In the SDK directory — register for linking and build
cd copilot-engine-sdk
npm link

# In your engine directory — link to local SDK
cd ../your-engine
npm link @github/copilot-engine-sdk

Changes to the SDK source are reflected immediately after running npm run build in the SDK directory.

Quick Start

import {
  PlatformClient,
  cloneRepo,
  finalizeChanges,
  createEngineMcpServer,
} from "@github/copilot-engine-sdk";

// Initialize the platform client for event reporting
const platform = new PlatformClient({
  apiUrl: process.env.GITHUB_PLATFORM_API_URL!,
  jobId: process.env.GITHUB_JOB_ID!,
  token: process.env.GITHUB_PLATFORM_API_TOKEN!,
});

// Clone the target repository
const repoLocation = cloneRepo({
  serverUrl: "https://github.com",
  repository: "owner/repo",
  gitToken: process.env.GITHUB_GIT_TOKEN!,
  branchName: "copilot/fix-issue-123",
  commitLogin: "copilot[bot]",
  commitEmail: "[email protected]",
});

// Send events to the platform
await platform.sendAssistantMessage({
  turn: 1,
  callId: "call-123",
  content: "I'll help you with that.",
  toolCalls: [],
});

// Finalize and push any remaining changes
finalizeChanges(repoLocation, "Apply fixes");

API Reference

PlatformClient

The main client for communicating with the platform API. Handles event reporting, progress updates, and history persistence.

const platform = new PlatformClient({
  apiUrl: string;   // Platform API URL
  jobId: string;    // Job identifier
  token: string;    // API authentication token
  nonce?: string;   // Optional job nonce
});

Event Methods:

  • sendAssistantMessage(opts) — report an assistant response with optional tool calls
  • sendToolMessage(opts) — report a tool result message
  • sendToolExecution(opts) — report a tool call and its result
  • sendModelCallFailure(opts) — report a model invocation failure
  • sendTruncation(opts) — report context truncation
  • sendResponse(opts) — report a final response

Progress Methods:

  • sendReportProgress(opts) — update PR title and description
  • sendCommentReply(opts) — reply to a PR comment

History Methods:

  • sendRawProgress(payloads) — send raw progress payloads (used for session history persistence)
  • fetchProgress(opts) — retrieve previously stored progress records

Git Utilities

Secure git operations with credential handling via http.extraHeader (tokens never appear in URLs or process listings).

import { cloneRepo, commitAndPush, finalizeChanges } from "@github/copilot-engine-sdk";

// Clone a repository with branch setup
const repoPath = cloneRepo({
  serverUrl: string;       // e.g., "https://github.com"
  repository: string;      // "owner/repo"
  gitToken: string;        // installation token
  branchName: string;      // branch to checkout or create
  commitLogin: string;     // git author name
  commitEmail: string;     // git author email
  cloneDir?: string;       // default: "/tmp/workspace"
});

// Commit and push changes (force push for engine-owned branches)
const result = commitAndPush(repoPath, "commit message");

// Finalize: commit + push any remaining uncommitted changes (non-fatal)
finalizeChanges(repoPath, "final commit message");

Branch handling:

  • If the branch exists on remote, it checks out the existing branch
  • If the branch doesn't exist, it creates a new branch from the default branch
  • Uses git ls-remote to distinguish "branch not found" from auth/network errors

MCP Server

The SDK includes an MCP server that can be used with any LLM SDK that supports the Model Context Protocol.

Tools provided:

  • report_progress — commits changes and updates the PR description with a progress checklist
  • reply_to_comment — replies to a PR review comment
import { createEngineMcpServer, startEngineMcpServer } from "@github/copilot-engine-sdk";

const server = createEngineMcpServer({
  workingDir: "/path/to/repo",
  push: true,                    // push commits to remote (default: true)
  platformClient: platform,      // optional: enables PR description updates
  logFile: "/tmp/mcp.log",       // optional: log file path (default: /tmp/mcp-server.log)
});

// Start as STDIO MCP server
await startEngineMcpServer(server);

Standalone usage (spawned as a child process):

node dist/mcp-server.js /path/to/working-directory

Set COPILOT_AGENT_PUSH=false to commit changes locally without pushing them. Pushing remains enabled when the variable is unset.

MCP Proxy Discovery

Discover user-configured MCP servers passed to the engine via the platform.

import { discoverMCPServers, isMCPProxyAvailable } from "@github/copilot-engine-sdk";

// Check if MCP proxy is available
if (isMCPProxyAvailable()) {
  const servers = discoverMCPServers();
  // Returns discovered MCP servers the user has configured
}

Event Factories

For advanced usage, create event objects directly:

import {
  createAssistantMessageEvent,
  createToolMessageEvent,
  createToolExecutionEvent,
  createModelCallFailureEvent,
  createTruncationEvent,
  createResponseEvent,
} from "@github/copilot-engine-sdk";

CLI — Local Testing

The SDK includes a CLI tool for testing engines locally without the full platform infrastructure. It simulates the platform API, clones a repo, and runs your engine command.

cd cli && go build ./cmd/engine-cli

engine-cli run "node dist/index.js" \
  --repo https://github.com/owner/repo \
  --problem-statement "Fix the bug in auth.ts" \
  --action fix \
  --timeout 5m

The CLI:

  • Clones the target repository to a temp directory
  • Starts a mock HTTP server that mimics the platform API
  • Spawns your engine with the required environment variables
  • Displays progress events in formatted output

See engine-cli run --help for all options.

Environment Variables

Engines receive these environment variables from the platform:

VariableDescription
GITHUB_JOB_IDUnique job identifier
GITHUB_PLATFORM_API_TOKENToken for platform API authentication
GITHUB_PLATFORM_API_URLPlatform API base URL
GITHUB_JOB_NONCEJob nonce for request signing
GITHUB_INFERENCE_TOKENToken for LLM inference calls
GITHUB_INFERENCE_URLInference API endpoint
GITHUB_GIT_TOKENToken for git operations

Documentation

Contributing

See CONTRIBUTING.md for local setup, build commands, and pull request guidance.

Support

See SUPPORT.md for how to ask questions or report bugs.

Security

See SECURITY.md for how to report security vulnerabilities.

License

See LICENSE.

版本与发布记录

@github/copilot-engine-sdk 共发布 9 个版本,首次发布于 2026/04/03;过去 12 个月发布了 9 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.3.1latest2026/09/022 个月前
0.3.02026/08/113 个月前
0.2.02026/07/223 个月前
0.1.22026/06/304 个月前
0.1.12026/06/264 个月前
0.1.02026/06/115 个月前

关于 @github/copilot-engine-sdk 的常见问题

@github/copilot-engine-sdk 是什么?

SDK for building engines on the GitHub Copilot agent platform

如何安装 @github/copilot-engine-sdk?

在项目目录运行 npm install @github/copilot-engine-sdk,或使用 pnpm add / yarn add / bun add。

@github/copilot-engine-sdk 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@github/copilot-engine-sdk 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@github/copilot-engine-sdk 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=20.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@github/copilot-engine-sdk 可以商用吗?

@github/copilot-engine-sdk 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@github/copilot-engine-sdk 的下载量有多少?

根据 npm 官方下载统计,@github/copilot-engine-sdk 在 2026/10/17 – 2026/11/15 这 30 天内被下载 10,362 次,日均约 345 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@github/copilot-engine-sdk 还在维护吗?

最新版本 0.3.1 发布于 2026/09/02(2 个月前);至今共发布 9 个版本,其中过去 12 个月发布了 9 个;首次发布于 2026/04/03。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。