Codestin Search App

注意

          Copilot SDK 当前处于 公共预览版. 功能和可用性可能会发生更改。

          GitHub Copilot SDK与GitHub Copilot 命令行界面 (CLI)通过 JSON-RPC 协议进行通信。 必须通过此协议显式公开功能才能在 SDK 中可用。 许多交互式 CLI 功能都是特定于终端的，不能以编程方式使用。

功能对比

在 SDK 中可用

功能	SDK 方法	备注
会话管理
创建会话	`createSession()`	完全配置支持
恢复会话	`resumeSession()`	使用无限会话工作区
断开会话连接	`disconnect()`	释放内存中资源
销毁会话	`destroy()`	请改用 `disconnect()`
删除会话	`deleteSession()`	从存储中删除
列出会话	`listSessions()`	所有存储会话
获取上一次会话	`getLastSessionId()`	用于快速恢复
获取前台会话	`getForegroundSessionId()`	多会话协调
设置前台会话	`setForegroundSessionId()`	多会话协调
Messaging
发送消息	`send()`	带有附件
发送和等待	`sendAndWait()`	在完成之前阻止
转向（即时模式）	`send({ mode: "immediate" })`	注入中间轮次而不中止
排队（入队模式）	`send({ mode: "enqueue" })`	顺序处理的缓冲区（默认值）
文件附件	`send({ attachments: [{ type: "file", path }] })`	图像自动编码和调整大小
目录附件	`send({ attachments: [{ type: "directory", path }] })`	附加目录上下文
获取历史记录	`getMessages()`	所有会话事件
中止	`abort()`	取消正在进行的请求
工具
注册自定义工具	`registerTools()`	完整的 JSON 架构支持
工具权限控制

          `onPreToolUse` 挂钩 | 允许/拒绝/询问 |

SDK 中不可用（仅限 CLI）

功能	CLI 命令/选项	原因
会话导出
导出到文件

          `--share`、`/share` | 不在协议中 |

解决方法

会话导出

此选项 --share 无法通过 SDK 使用。要解决此问题：

手动收集事件： 订阅会话事件并生成自己的导出：

TypeScript

const events: SessionEvent[] = [];
session.on((event) => events.push(event));
// ... after conversation ...
const messages = await session.getMessages();
// Format as markdown yourself

const events: SessionEvent[] = [];
session.on((event) => events.push(event));
// ... after conversation ...
const messages = await session.getMessages();
// Format as markdown yourself

直接使用 CLI 进行一次性导出。

权限控制

SDK 使用默认拒绝权限模型。除非应用提供 onPermissionRequest 处理程序，否则将拒绝所有权限请求（文件写入、shell 命令、URL 提取和其他请求）。

而不是 --allow-all-paths 或 --yolo，使用权限处理程序：

TypeScript

const session = await client.createSession({
  onPermissionRequest: approveAll,
});

const session = await client.createSession({
  onPermissionRequest: approveAll,
});

令牌使用情况跟踪

订阅使用情况事件而不是 /usage：

TypeScript

session.on("assistant.usage", (event) => {
  console.log("Tokens used:", {
    input: event.data.inputTokens,
    output: event.data.outputTokens,
  });
});

session.on("assistant.usage", (event) => {
  console.log("Tokens used:", {
    input: event.data.inputTokens,
    output: event.data.outputTokens,
  });
});

上下文压缩

配置自动压缩或手动触发，而不是 /compact。

TypeScript

// Automatic compaction via config
const session = await client.createSession({
  infiniteSessions: {
    enabled: true,
    backgroundCompactionThreshold: 0.80,  // Start background compaction at 80% context utilization
    bufferExhaustionThreshold: 0.95,      // Block and compact at 95% context utilization
  },
});

// Manual compaction (experimental)
const result = await session.rpc.compaction.compact();
console.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`);

// Automatic compaction via config
const session = await client.createSession({
  infiniteSessions: {
    enabled: true,
    backgroundCompactionThreshold: 0.80,  // Start background compaction at 80% context utilization
    bufferExhaustionThreshold: 0.95,      // Block and compact at 95% context utilization
  },
});

// Manual compaction (experimental)
const result = await session.rpc.compaction.compact();
console.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`);

注意

阈值是上下文利用率（0.0-1.0），而不是绝对令牌计数。

计划管理

以编程方式读取和写入会话计划：

TypeScript

// Read the current plan
const plan = await session.rpc.plan.read();
if (plan.exists) {
  console.log(plan.content);
}

// Update the plan
await session.rpc.plan.update({ content: "# My Plan\n- Step 1\n- Step 2" });

// Delete the plan
await session.rpc.plan.delete();

// Read the current plan
const plan = await session.rpc.plan.read();
if (plan.exists) {
  console.log(plan.content);
}

// Update the plan
await session.rpc.plan.update({ content: "# My Plan\n- Step 1\n- Step 2" });

// Delete the plan
await session.rpc.plan.delete();

消息引导

在不中断当前 LLM 回合的情况下插入一条消息：

TypeScript

// Steer the agent mid-turn
await session.send({ prompt: "Focus on error handling first", mode: "immediate" });

// Default: enqueue for next turn
await session.send({ prompt: "Next, add tests" });

// Steer the agent mid-turn
await session.send({ prompt: "Focus on error handling first", mode: "immediate" });

// Default: enqueue for next turn
await session.send({ prompt: "Next, add tests" });

协议限制

SDK 只能访问通过 CLI 的 JSON-RPC 协议公开的功能。如果您需要当前不可用的 CLI 功能：

检查替代项： 许多功能具有 SDK 等效项（请参阅上面的解决方法）。
直接使用 CLI： 对于一次性操作，请调用 CLI。
请求该功能： 在 github/copilot-sdk 存储库中提出问题以请求协议支持。

版本兼容性

SDK 协议范围	CLI 协议版本	兼容性
v2-v3	v3	完全支持
v2-v3	v2	支持自动 v2 适配器

SDK 在启动时与 CLI 协商协议版本。 SDK 支持协议版本 2 到 3。连接到 v2 CLI 服务器时，SDK 会自动调整 tool.call 和 permission.request 消息到 v3 事件模型，无需更改代码。

可以在运行时检查版本：

TypeScript

const status = await client.getStatus();
console.log("Protocol version:", status.protocolVersion);

const status = await client.getStatus();
console.log("Protocol version:", status.protocolVersion);

SDK 和 CLI 兼容性

谁可以使用此功能？

在本文中

功能对比

在 SDK 中可用

SDK 中不可用（仅限 CLI）

解决方法

会话导出

权限控制

令牌使用情况跟踪

上下文压缩

计划管理

消息引导

协议限制

版本兼容性