# @github/copilot-engine-sdk 中文文档

规范地址：https://npmcn.com/package/%40github/copilot-engine-sdk/

版本：0\.3\.1
npm 元数据更新时间：2026-10-15T16:20:25.188Z
中文译文更新时间：2026-11-16T11:15:15.669Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40github/copilot-engine-sdk
原文对照：https://npmcn.com/package/%40github/copilot-engine-sdk/?lang=original
项目主页：https://github.com/github/copilot-engine-sdk#readme
源码仓库：https://github.com/github/copilot-engine-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.3 MB，32 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：2 个
- 首次发布：2026-04-02T16:32:32.684Z
- 最新版本发布：2026-09-01T19:51:16.522Z
- 近 30 天下载量：10362（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

在 GitHub 副驾驶代理平台上制造引擎的 SDK

## 安装

```sh
npm install @github/copilot-engine-sdk
```

也可以使用：`pnpm add @github/copilot-engine-sdk`、`yarn add @github/copilot-engine-sdk`、`bun add @github/copilot-engine-sdk`

## README

# @github/副驾驶-引擎-sdk

> **注:** 这是一个内部用于某些整合的图书馆. 它不是一个支持的集成路径,预览或被发布的产品.

SDK用于GitHub副驾驶代理平台上制造引擎.

## 概览

副驾驶引擎SDK提供所有你需要的,在GitHub副驾驶代理平台上运行的引擎:

-   **平台客户端** 向API平台发送结构化活动(协助信息、工具执行、进度更新)
-   **Git 公用事业** ——克隆寄存器,承诺并用安全的证书处理来推动更改
-   **MCP 服务器** - 一个示范背景协议服务器曝光 `report_progress` 财务报告和审定财务报表 `reply_to_comment` 工具
-   **MCP 代理发现** ——发现并连接用户配置的MCP服务器
-   **事件工厂** ——为自定义事件管道创建打字平台事件
-   **国 际** ——能模拟发展平台的本地测试手段
-   **[融合指南](https://npmcn.com/package/%40github/copilot-engine-sdk/docs/integration-guide.md)** ——逐步引导发动机建设

## 安装

在此软件包发布到软件包注册之前, 从 GitHub 直接安装 :

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

然后运行 `npm install`。 。 。 .

### 地方发展

用于本地开发, 复制 SDK :

```bash
# 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
```

对 SDK 源的更改在运行后立即反映 `npm run build` 在SDK目录中.

## 快速启动

```typescript
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: "copilot@github.com",
});

// 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 参考

### 平台客户端

与平台API沟通的主要客户端. 处理事件报告、最新进展和历史的持久性.

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

**活动方法:**

-   `sendAssistantMessage(opts)` - 报告有可选工具呼叫的助理响应
-   `sendToolMessage(opts)` 报告工具结果信息
-   `sendToolExecution(opts)` 报告一个工具呼叫及其结果
-   `sendModelCallFailure(opts)` 报告模式引用失败
-   `sendTruncation(opts)` - 报告上下文缩短
-   `sendResponse(opts)` - 报告最后答复

**方法:**

-   `sendReportProgress(opts)` ——更新PR标题和描述
-   `sendCommentReply(opts)` - 对公关评论的答复

**历史方法:**

-   `sendRawProgress(payloads)` 发送原始进度有效载荷(用于会议历史持久性)
-   `fetchProgress(opts)` ——取回以前存储的进度记录

### Git 公用事业

通过认证处理,确保有固定操作 `http.extraHeader` (磁盘从未出现在 URL 或进程列表中).

```typescript
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");
```

**分支处理 :**

-   如果分行存在于远程上, 它检查现有的分行
-   如果分支不存在, 它从默认分支创建出一个新的分支
-   用途 `git ls-remote` 以区分“未找到的分支”和 auth/网络错误

### MCP 服务器

SDK包括一个MCP服务器,可用于任何支持"模型上下文协议"的LLM SDK.

**提供的工具:**

-   `report_progress` - 进行修改并用进度核对表更新PR说明
-   `reply_to_comment` 对公关审查意见的答复

```typescript
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);
```

**独立使用** (作为儿童过程生育):

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

设定 `COPILOT_AGENT_PUSH=false` 在当地进行变革,而无需推动。 当变量未被设定时, 仍可进行推进 .

### MCP 代理发现

发现用户配置的MCP服务器通过平台传递给引擎.

```typescript
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
}
```

### 事件工厂

对于高级用途,直接创建事件对象 :

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

## CLI - 本地测试

SDK包括一个CLI工具,用于本地测试引擎而无需完整的平台基础设施. 它模拟了平台API,克隆了repo,并运行了你的引擎命令.

```bash
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
```

国家行动倡议:

-   将目标仓库克隆为临时目录
-   启动模拟平台 API 的模拟 HTTP 服务器
-   将引擎与所需的环境变量相融合
-   以格式化输出显示进度事件

见 `engine-cli run --help` 所有选项.

## 环境变量

引擎从平台接收这些环境变量:

| 变量 | 说明 |
| --- | --- |
| `GITHUB_JOB_ID` | 唯一任务标识符 |
| `GITHUB_PLATFORM_API_TOKEN` | Token 用于平台 API 认证 |
| `GITHUB_PLATFORM_API_URL` | 平台 API 基础 URL |
| `GITHUB_JOB_NONCE` | 任务非请求签名 |
| `GITHUB_INFERENCE_TOKEN` | 用于 LLM 推论 |
| `GITHUB_INFERENCE_URL` | 推断 API 端点 |
| `GITHUB_GIT_TOKEN` | Git 操作键 |

## 文档

-   **[融合指南](https://npmcn.com/package/%40github/copilot-engine-sdk/docs/integration-guide.md)** ——从零开始建设发动机的分步指南

## 捐款

见 [捐款额](https://npmcn.com/package/%40github/copilot-engine-sdk/CONTRIBUTING.md) 用于本地设置、构建命令和拉动请求指导.

## 支助

见 [支助](https://npmcn.com/package/%40github/copilot-engine-sdk/SUPPORT.md) 用于询问或报告错误.

## 警卫

见 [警卫](https://npmcn.com/package/%40github/copilot-engine-sdk/SECURITY.md) 如何报告安全弱点.

## 许可证

见 [自由主义](https://npmcn.com/package/%40github/copilot-engine-sdk/LICENSE)。 。 。 .

## 常见问题

### @github/copilot-engine-sdk 是什么？

在 GitHub 副驾驶代理平台上制造引擎的 SDK

### 如何安装 @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 和提交记录判断。

