后端服务模式让 CLI 作为独立进程持续运行，SDK 通过 TCP/cliUrl 连接而不是每次启动新进程。一个 CLI 服务可以被多个 Node.js 进程同时连接，节省启动时间，适合微服务架构和高并发场景。

GitHub Copilot SDK 后端服务模式：CLI 作为持久化 AI 服务端

适用场景

• 多进程架构：多个 Worker 进程需要共享同一个 Copilot 连接
• 微服务：API 网关和业务服务分离部署
• 性能要求高：避免每次请求都启动 CLI 进程的开销（冷启动 300-500ms）

启动 CLI 服务

先在独立进程中启动 Copilot CLI 监听模式：

# 启动 CLI 监听，绑定到指定端口
gh copilot serve --port 3001

# 或者用环境变量指定端口
COPILOT_CLI_PORT=3001 gh copilot serve

CLI 启动后会持续运行并等待 SDK 连接。

SDK 连接到已运行的 CLI

import { createSession } from '@github/copilot-sdk'

// 通过 cliUrl 连接到已运行的 CLI 服务
const session = await createSession({
  cliUrl: 'http://localhost:3001'  // CLI 服务地址
})

const response = await session.sendPrompt({
  messages: [{ role: 'user', content: 'Hello!' }]
})

多进程共享 CLI 服务

// process-a.ts（API 服务）
const session = await createSession({
  cliUrl: 'http://localhost:3001',
  sessionId: `api-${requestId}`
})

// process-b.ts（后台任务服务）
const session = await createSession({
  cliUrl: 'http://localhost:3001',
  sessionId: `task-${taskId}`
})

两个进程连接同一个 CLI 实例，但每个 Session 通过 sessionId 隔离。

使用 Process Manager 管理 CLI 服务

生产环境推荐用 PM2 管理 CLI 进程：

# 安装 PM2
npm install -g pm2

# 创建 PM2 配置
cat > ecosystem.config.js << 'EOF'
module.exports = {
  apps: [{
    name: 'copilot-cli',
    script: 'gh',
    args: 'copilot serve --port 3001',
    autorestart: true,
    max_restarts: 10,
    min_uptime: '5s'
  }]
}
EOF

# 启动
pm2 start ecosystem.config.js
pm2 save  # 设置开机自启

健康检查与重连

async function createSessionWithRetry(cliUrl: string, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      return await createSession({ cliUrl })
    } catch (error) {
      if (i === retries - 1) throw error
      // 等待 CLI 服务就绪
      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)))
    }
  }
}

与本地 CLI 模式的对比

	本地 CLI 模式	后端服务模式
适用	单进程、个人项目	多进程、微服务
冷启动	每次 300-500ms	一次启动后 <5ms
资源	每进程一个 CLI	多进程共享
管理	自动	需要 PM2 等工具

常见问题

Q: CLI 服务挂了，已连接的 Session 怎么处理？

A: 连接中断后 SDK 会抛出错误。需要在应用层实现重连逻辑，检测到连接失败时等待 CLI 服务恢复后重新创建 Session。

Q: 多少个进程可以共享一个 CLI 服务？

A: 取决于 CLI 服务的处理能力和 Copilot 的并发限制。建议单个 CLI 服务承接不超过 20 个并发 Session，超过时部署多个 CLI 服务实例并在应用层做负载均衡。

Q: cliUrl 支持远程地址吗？

A: 支持。可以把 CLI 服务部署在独立服务器上，SDK 通过网络连接。注意要在防火墙规则中只允许内网访问，CLI 服务本身没有认证机制。