GitHub Copilot SDK客户端选项：配置AI行为的各种参数

【免费下载链接】copilot-sdk Multi-platform SDK for integrating GitHub Copilot Agent into apps and services 项目地址: https://gitcode.com/GitHub_Trending/co/copilot-sdk

GitHub Copilot SDK是一个强大的多平台软件开发工具包，让开发者能够将GitHub Copilot Agent深度集成到应用程序和服务中。通过丰富的客户端选项，您可以精确控制AI助手的行为、性能和功能。本文将详细介绍GitHub Copilot SDK的核心配置参数，帮助您快速掌握如何定制化Copilot的AI行为。

GitHub Copilot SDK提供了灵活的客户端选项配置，让开发者能够根据应用场景调整AI助手的行为。无论您需要构建聊天机器人、代码助手还是智能问答系统，都可以通过这些参数实现精准控制。

🚀 客户端选项概览

GitHub Copilot SDK的配置分为两个主要层次：客户端级别配置和会话级别配置。客户端配置影响整个SDK实例的行为，而会话配置则针对单个对话会话进行定制。

客户端配置（CopilotClientOptions）

客户端配置在创建CopilotClient实例时设置，影响所有通过该客户端创建的会话：

参数	类型	描述	默认值
connection	RuntimeConnection	运行时连接方式（stdio、TCP、URI）	forStdio()
mode	"empty" | "copilot-cli"	SDK默认策略模式	"copilot-cli"
workingDirectory	string	运行时进程的工作目录	继承当前进程
baseDirectory	string	Copilot数据存储目录	~/.copilot
logLevel	"none" | "error" | "warning" | "info" | "debug" | "all"	运行时日志级别	"info"
gitHubToken	string	GitHub认证令牌	-
useLoggedInUser	boolean	是否使用已登录用户	true
telemetry	TelemetryConfig	OpenTelemetry配置	-
sessionFs	SessionFsConfig	自定义会话文件系统提供程序	-

示例代码：创建自定义配置的客户端

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

const client = new CopilotClient({
    connection: RuntimeConnection.forUri("localhost:4321"),
    mode: "empty",
    baseDirectory: "/var/lib/my-app/copilot",
    logLevel: "debug",
    gitHubToken: "gho_xxx",
    useLoggedInUser: false,
    telemetry: {
        otlpEndpoint: "http://localhost:4318",
        exporterType: "otlp-http"
    }
});

🔧 会话配置（SessionConfig）

会话配置在创建单个会话时设置，允许您为每个对话定义特定的行为：

基础模型配置

参数	描述	示例值
model	使用的AI模型	"gpt-5.4", "auto"
reasoningEffort	推理努力级别	"low", "medium", "high", "xhigh"
reasoningSummary	推理摘要模式	"none", "concise", "detailed"
contextTier	上下文窗口层级	"default", "long_context"
modelCapabilities	模型能力覆盖	{ supports: { vision: true } }

工具和功能控制

参数	描述	用途
tools	自定义工具列表	扩展AI功能
availableTools	可用工具过滤器	限制工具访问
excludedTools	排除工具列表	禁用特定工具
excludedBuiltinAgents	排除内置代理	隐藏内置AI代理
customAgents	自定义代理配置	创建专用AI角色
systemMessage	系统消息配置	定义AI角色和行为
streaming	启用流式响应	实时获取AI回复

示例：创建专业代码审查会话

from copilot import CopilotClient, PermissionHandler

client = CopilotClient()
session = await client.create_session(
    model="gpt-5.4",
    system_message={
        "content": "你是一个专业的代码审查助手，专注于安全、性能和代码质量。",
        "mode": "customize",
        "sections": {
            "tone": {"action": "replace", "content": "以专业、建设性的语气回复"},
            "code_change_rules": {"action": "remove"}
        }
    },
    tools=[code_review_tool, security_scan_tool],
    availableTools=["custom:code_review", "custom:security_scan", "builtin:*"],
    excludedTools=["builtin:web_search"],
    streaming=True,
    reasoningEffort="high"
)

🛠️ 高级配置选项

1. 多租户配置

在多用户应用中，您需要为每个用户创建独立的会话配置：

func createUserSession(ctx context.Context, userID string, userToken string) (*copilot.Session, error) {
    client := copilot.NewClient(&copilot.ClientOptions{
        GitHubToken:     userToken,
        UseLoggedInUser: copilot.Bool(false),
        BaseDirectory:   fmt.Sprintf("/var/lib/app/copilot/%s", userID),
    })
    
    session, err := client.CreateSession(ctx, &copilot.SessionConfig{
        SessionID: fmt.Sprintf("user-%s-%d", userID, time.Now().Unix()),
        Model:     "gpt-5.4",
        SessionLimits: &copilot.SessionLimitsConfig{
            MaxTokens:    10000,
            MaxRequests:  100,
            WindowHours:  24,
        },
        EnableSessionTelemetry: false,
    })
    return session, err
}

2. 自定义AI提供商（BYOK）

GitHub Copilot SDK支持Bring Your Own Key（BYOK）模式，让您使用自己的AI提供商：

await using var session = await client.CreateSessionAsync(new SessionConfig
{
    Model = "gpt-4",
    Provider = new ProviderConfig
    {
        Type = "openai",
        BaseUrl = "https://api.openai.com/v1",
        ApiKey = "sk-your-openai-key",
        ModelId = "gpt-4-turbo",
        WireModel = "gpt-4-turbo-preview"
    },
    Tools = [customTool1, customTool2]
});

3. MCP服务器集成

Model Context Protocol（MCP）允许集成外部工具服务器：

const session = await client.createSession({
    model: "auto",
    mcpServers: {
        github: {
            type: "http",
            url: "https://api.githubcopilot.com/mcp/"
        },
        weather: {
            type: "stdio",
            command: "npx",
            args: ["@modelcontextprotocol/server-weather"]
        }
    },
    enableConfigDiscovery: true
});

4. 会话限制和配额控制

let session = client.create_session(
    SessionConfig::default()
        .with_model("gpt-5.4")
        .with_session_limits(SessionLimitsConfig {
            max_tokens: Some(5000),
            max_requests: Some(50),
            window_hours: Some(1),
        })
        .with_available_tools(vec!["custom:calculator", "custom:timezone"])
        .with_excluded_tools(vec!["builtin:web_search"])
        .with_skip_custom_instructions(true)
        .with_custom_agents_local_only(true)
).await?;

📊 性能优化选项

流式响应配置

var session = client.createSession(
    new SessionConfig()
        .setModel("gpt-5.4")
        .setStreaming(true)
        .setIncludeSubAgentStreamingEvents(false)
        .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
        .setTools(List.of(getWeatherTool, getTimeTool))
).get();

大工具输出处理

session = await client.create_session(
    model="gpt-5.4",
    largeOutput={
        "enabled": True,
        "maxSize": 1024 * 1024,  # 1MB
        "tempDir": "/tmp/copilot"
    },
    configDirectory="/var/cache/copilot",
    workingDirectory="/project/src"
)

🔐 安全和权限控制

权限处理配置

const session = await client.createSession({
    model: "auto",
    onPermissionRequest: async (request, invocation) => {
        // 自定义权限处理逻辑
        if (request.action === "file_read") {
            return { decision: "approve_once" };
        }
        return { decision: "deny" };
    },
    onMcpAuthRequest: async (request) => {
        // 处理MCP OAuth请求
        return { kind: "token", token: "your-oauth-token" };
    },
    onUserInputRequest: async (request) => {
        // 处理用户输入请求
        return { text: "用户确认执行操作" };
    }
});

会话隔离配置

session, err := client.CreateSession(ctx, &copilot.SessionConfig{
    Model: "gpt-5.4",
    SkipCustomInstructions: true,
    CustomAgentsLocalOnly: true,
    CoauthorEnabled: false,
    ManageScheduleEnabled: false,
    MCPOAuthTokenStorage: "in-memory",
    EnableMcpApps: false
})

🎯 最佳实践配置示例

场景1：代码助手应用

const codeAssistant = await client.createSession({
    model: "gpt-5.4",
    systemMessage: {
        content: "你是一个专业的代码助手，专注于TypeScript、Python和Go开发。",
        mode: "customize",
        sections: {
            identity: { action: "replace", content: "代码专家" },
            guidelines: { 
                action: "append", 
                content: "\n* 优先使用TypeScript\n* 遵循ESLint规则\n* 提供单元测试示例"
            }
        }
    },
    tools: [codeFormatter, testGenerator, docGenerator],
    availableTools: ["custom:*", "builtin:code_search"],
    excludedTools: ["builtin:web_search"],
    streaming: true,
    reasoningEffort: "medium"
});

场景2：客服聊天机器人

customer_service = await client.create_session(
    model="gpt-4",
    system_message={
        "content": "你是一个友好的客服助手，帮助用户解决产品问题。",
        "mode": "customize",
        "sections": {
            "tone": {"action": "replace", "content": "使用友好、耐心的语气回复"},
            "guidelines": {"action": "append", "content": "\n* 始终保持礼貌\n* 不要做出无法兑现的承诺"}
        }
    },
    tools=[order_lookup, ticket_creator, faq_search],
    enable_session_telemetry=True,
    mcp_servers={
        "knowledge_base": {
            "type": "http",
            "url": "https://kb.internal.company.com/mcp"
        }
    }
)

📈 监控和诊断配置

OpenTelemetry集成

var client = new CopilotClient(new CopilotClientOptions
{
    Telemetry = new TelemetryConfig
    {
        OtlpEndpoint = "http://localhost:4318",
        ExporterType = "otlp-http",
        SourceName = "my-copilot-app",
        CaptureContent = true
    },
    OnGetTraceContext = () => {
        var carrier = new Dictionary<string, string>();
        propagation.Inject(Activity.Current?.Context ?? default, carrier);
        return carrier;
    }
});

会话生命周期钩子

const session = await client.createSession({
    model: "auto",
    hooks: {
        onSessionStart: async (input) => {
            console.log(`会话开始: ${input.sessionId}`);
            return {};
        },
        onSessionEnd: async (input) => {
            console.log(`会话结束: ${input.sessionId}, 原因: ${input.reason}`);
            return {};
        },
        onUserPromptSubmitted: async (input) => {
            console.log(`用户输入: ${input.prompt}`);
            return {};
        }
    }
});

🎨 视觉和UI配置

Canvas渲染器配置

const session = await client.createSession({
    model: "gpt-5.4",
    requestCanvasRenderer: true,
    canvases: [{
        id: "chart-canvas",
        title: "数据图表",
        capabilities: ["chart", "table"],
        handler: chartCanvasHandler
    }],
    canvasProvider: {
        id: "my-app-canvas-provider",
        name: "My App Canvas Provider"
    },
    extensionInfo: {
        source: "my-app",
        name: "main-extension"
    }
});

🔧 故障排除和调试

调试模式配置

# 环境变量配置
export COPILOT_LOG_LEVEL=debug
export COPILOT_HOME=/tmp/copilot-debug

# 客户端配置
const client = new CopilotClient({
    logLevel: "debug",
    baseDirectory: "/tmp/copilot-debug",
    env: {
        COPILOT_DEBUG: "true",
        NODE_OPTIONS: "--inspect"
    }
});

连接故障恢复

client := copilot.NewClient(&copilot.ClientOptions{
    Connection: copilot.URIConnection{
        URL: "localhost:4321",
        Timeout: 30 * time.Second,
        RetryAttempts: 3,
    },
    SessionIdleTimeoutSeconds: 300,
})

📋 配置选项快速参考表

类别	关键配置	用途	推荐场景
基础配置	model, reasoningEffort, contextTier	控制AI模型行为	所有应用
工具管理	tools, availableTools, excludedTools	扩展和限制功能	专用助手
安全控制	skipCustomInstructions, customAgentsLocalOnly	隔离和限制	多租户应用
性能优化	streaming, largeOutput, sessionLimits	资源控制	高并发场景
集成扩展	mcpServers, customAgents, provider	第三方集成	企业应用
监控诊断	telemetry, hooks, logLevel	运维监控	生产环境

🚀 开始使用

要开始配置GitHub Copilot SDK，首先安装SDK：

# Node.js
npm install @github/copilot-sdk

# Python
pip install github-copilot-sdk

# Go
go get github.com/github/copilot-sdk/go

# Rust
cargo add github-copilot-sdk

# .NET
dotnet add package GitHub.Copilot.SDK

# Java
<dependency>
    <groupId>com.github</groupId>
    <artifactId>copilot-sdk-java</artifactId>
</dependency>

然后创建您的第一个配置化客户端：

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

const client = new CopilotClient({
    // 客户端级别配置
    logLevel: "info",
    baseDirectory: "./copilot-data"
});

const session = await client.createSession({
    // 会话级别配置
    model: "auto",
    streaming: true,
    tools: [customTool],
    systemMessage: {
        content: "你是一个有帮助的AI助手"
    }
});

通过灵活配置GitHub Copilot SDK的客户端选项，您可以构建出功能强大、行为可控的AI应用。无论是简单的聊天机器人还是复杂的企业级AI系统，这些配置参数都能帮助您实现精准的AI行为控制。

【免费下载链接】copilot-sdk Multi-platform SDK for integrating GitHub Copilot Agent into apps and services 项目地址: https://gitcode.com/GitHub_Trending/co/copilot-sdk